You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by ri...@apache.org on 2016/02/09 15:42:24 UTC
[3/7] brooklyn-docs git commit: moved code/github instrutions to
website not guide, and tidy structure
moved code/github instrutions to website not guide, and tidy structure
many more cross-links, and more detail in the menus
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/6b1b3307
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/6b1b3307
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/6b1b3307
Branch: refs/heads/master
Commit: 6b1b33077a7c1505108301514c0aefd0f7df5aac
Parents: b27443e
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Mon Feb 8 14:20:10 2016 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Mon Feb 8 16:13:09 2016 +0000
----------------------------------------------------------------------
guide/dev/code/index.md | 92 ------
guide/dev/code/no-submodules.md | 20 --
guide/dev/code/submodules.md | 229 ---------------
guide/dev/env/index.md | 13 -
guide/dev/index.md | 5 +-
website/developers/code/git-more.md | 290 +++++++++++++++++++
website/developers/code/index.md | 82 ++++++
.../committers/merging-contributed-code.md | 2 +-
website/developers/how-to-contribute.md | 3 +-
website/developers/index.md | 7 +-
website/developers/links.md | 3 +-
11 files changed, 384 insertions(+), 362 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/guide/dev/code/index.md
----------------------------------------------------------------------
diff --git a/guide/dev/code/index.md b/guide/dev/code/index.md
deleted file mode 100644
index 955658f..0000000
--- a/guide/dev/code/index.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-title: Get the Code
-layout: website-normal
-children:
-- submodules.md
-- no-submodules.md
----
-
-## The Basics
-
-The Apache Brooklyn source code is available at [GitHub apache/brooklyn](http://github.com/apache/brooklyn),
-together with many [`brooklyn-*` sub-module projects](https://github.com/apache?query=brooklyn).
-Checkout and build all the submodules with:
-
-{% highlight bash %}
-git clone http://github.com/apache/brooklyn/
-cd brooklyn
-git submodule init
-git submodule update --remote --merge --recursive
-
-mvn clean install
-{% endhighlight %}
-
-This will produce an artifact in `brooklyn-dist/dist/brooklyn-dist-0.9.0-SNAPSHOT-dist.tar.gz` <!-- BROOKLYN_VERSION -->
-which you can use [in the usual way](../../start/running.html).
-Some options which may be useful:
-
-* Use `--depth 1` with `git clone` to skip the history (much faster but your `git log` will be incomplete)
-* Use `-DskipTests` with `mvn` to skip tests (again much faster but it won't catch failures)
-* See below if you don't want to use submodules
-
-Thereafter to update the code in submodules, we strongly recommend doing this:
-
- git pull && git submodule update --remote --merge --recursive
-
-This merges the latest upstream changes into the current branch of each sub-module on your local machine,
-giving nice errors on conflicts.
-It's fine also to do branching and pulling in each submodule,
-but running `update` without these parameters can cause chaos!
-The [submodules](submodules.html) page will elaborate on potential chaos and pitfalls,
-and it provides instructions for setting up an alias `git sup` for this command.
-
-
-### If You Can't Stand Submodules
-
-[These instructions](no-submodules.html) can help setting up a local environment
-which does not rely on submodules.
-
-
-### Contributing a Small Change
-
-If you're making a small change in one project, consider just using that project.
-Whether you use this uber-project or not, to [contribute]({{ site.path.website }}/developers/how-to-contribute.html)
-you'll need to follow the usual fork->work->push->pull-request process.
-
-To understand where you might want to make your change,
-look at the [code structure](structure.html).
-
-
-### Bigger and Regular Changes
-
-Regular contributors will typically have their own fork for each of the submodule projects,
-and will probably want some other settings and tips [as described here](submodules.html).
-
-
-## History, Tags, and Workflow
-
-There are branches for each released version and tags for various other milestones.
-
-As described in more detail [here](submodules.html), we primarily use submodule remote branch tracking
-rather than submodule SHA1 ID's.
-
-The history prior to `0.9.0` is imported from the legacy `incubator-brooklyn` repo for reference and history only.
-Visit that repo to build those versions; they are not intended to build here.
-(Although this works:
-`mkdir merged ; for x in brooklyn-* ; do pushd $x ; git checkout 0.8.0-incubating ; cp -r * ../merged ; popd ; cd merged ; mvn clean install`.)
-
-
-## Next Steps
-
-If you're interested in building and editing the code, you probably want to become familiar with these:
-
-* [Product structure](structure.html)
-* [Maven setup](../env/maven-build.html)
-* [IDE setup](../env/ide/)
-* [Tests](tests.html)
-* [Tips](../tips/)
-* [Remote Debugging](../tips/debugging-remote-brooklyn.html)
-
-Where things aren't documented **please ask us** at
-[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/brooklyn-dev/)
-so we can remedy this!
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/guide/dev/code/no-submodules.md
----------------------------------------------------------------------
diff --git a/guide/dev/code/no-submodules.md b/guide/dev/code/no-submodules.md
deleted file mode 100644
index 4516653..0000000
--- a/guide/dev/code/no-submodules.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: Not Using Submodules
-layout: website-normal
----
-
-If you don't want to use submodules, this will achieve the same result:
-
-{% highlight bash %}
-mkdir apache-brooklyn
-cd apache-brooklyn
-git clone http://github.com/apache/brooklyn/
-git clone http://github.com/apache/brooklyn-ui/
-git clone http://github.com/apache/brooklyn-server/
-git clone http://github.com/apache/brooklyn-client/
-git clone http://github.com/apache/brooklyn-docs/
-git clone http://github.com/apache/brooklyn-library/
-git clone http://github.com/apache/brooklyn-dist/
-ln -s brooklyn/pom.xml .
-mvn clean install
-{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/guide/dev/code/submodules.md
----------------------------------------------------------------------
diff --git a/guide/dev/code/submodules.md b/guide/dev/code/submodules.md
deleted file mode 100644
index 5348dd4..0000000
--- a/guide/dev/code/submodules.md
+++ /dev/null
@@ -1,229 +0,0 @@
----
-title: Git Submodules
-layout: website-normal
----
-
-## Setting Up Forks
-
-If you're contributing or working a lot on a feature,
-you'll probably want your own forks and a slightly different git remote setup.
-
-You can create forks of each Brooklyn repo [in the GitHub UI](https://github.com/apache?query=brooklyn)
-or, if you have the command-line tool `hub` ([described here](https://github.com/github/hub), or `sudo npm install -g hub`),
-by running this command:
-
-{% highlight bash %}
-hub fork; git submodule foreach 'hub fork'
-{% endhighlight %}
-
-The basic clone-and-get-submodules process in the ["Get the code" page](index.html)
-retrieved the upstream repos, but it gave those remotes the name `origin`.
-If you have forks, `upstream` is a more accurate name. You can rename the origin remotes with:
-
-{% highlight bash %}
-git remote rename origin upstream; git submodule foreach 'git remote rename origin upstream'
-{% endhighlight %}
-
-You'll now likely want to add the remote `origin` for your fork:
-
-{% highlight bash %}
-if [ -z "$GITHUB_ID" ] ; then echo -n "Enter your GitHub ID id: " ; read GITHUB_ID ; fi
-git remote add origin git@github.com:${GITHUB_ID}/apache
-git submodule foreach 'git remote add origin git@github.com:${GITHUB_ID}/${name}'
-{% endhighlight %}
-
-And if you created the fork in the GitHub UI, you may want to create a remote named by your
-GitHub ID as well (if you used `hub` it will have done it for you):
-
-{% highlight bash %}
-if [ -z "$GITHUB_ID" ] ; then echo -n "Enter your GitHub ID id: " ; read GITHUB_ID ; fi
-git remote add ${GITHUB_ID} git@github.com:${GITHUB_ID}/apache
-git submodule foreach 'git remote add ${GITHUB_ID} git@github.com:${GITHUB_ID}/${name}'
-{% endhighlight %}
-
-You probably also want the default `push` target to be your repo in the `origin` remote:
-
-{% highlight bash %}
-git config remote.pushDefault origin; git submodule foreach 'git config remote.pushDefault origin'
-{% endhighlight %}
-
-Optionally, if you're interested in reviewing pull requests,
-you may wish to have `git` automatically check out PR branches:
-
-{% highlight bash %}
-git config --local --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*'
-git submodule foreach "git config --local --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*'"
-git pull ; git submodule foreach 'git pull'
-{% endhighlight %}
-
-And also optionally, to set up the official Apache repo as a remote ---
-useful if GitHub is slow to update (and required if you're a committer):
-
-{% highlight bash %}
-git remote add apache-git https://git-wip-us.apache.org/repos/asf/brooklyn
-git submodule foreach 'git remote add apache-git https://git-wip-us.apache.org/repos/asf/${name}'
-{% endhighlight %}
-
-**That's it.** Test that it's all working by browsing the submodules and issuing `git remote -v` and `git pull` commands. Also see the aliases below.
-
-To work on code in a branch, in any of the submodules, you can simply do the following:
-
-{% highlight bash %}
-% git branch my-new-feature-branch upstream/master
-% git checkout my-new-feature-branch
-(make some commits)
-% git push
-To https://github.com/your_account/brooklyn.git
- * [new branch] my-new-feature-branch -> my-new-feature-branch
-{% endhighlight %}
-
-Note how the branch is tracking `upstream/master` for the purpose of `git pull`,
-but a `git push` goes to the fork.
-When you're finished, don't forget to go to the UI of your repo to open a pull request.
-
-
-
-## Multi-Project Changes
-
-Cross-project changes will require multiple PRs:
-try to minimise these, especially where one depends on another,
-and especially especially where two depend on each other -- that is normally a sign of broken backwards compatibility!
-Open the PRs in dependency order and assist reviewers by including the URLs of any upstream dependency PRs
-in the dependent PR to help reviewers
-(dependency PRs will then include a "mention" comment of the dependent PR).
-
-For information on reviewing and committing PRs, see [the committer's guide]({{site.path.website}}/developers/committers/merging-contributed-code.html).
-
-
-## Other Things You Should Know
-
-Our submodules track **branches**, rather than specific commits,
-although due to the way `git` works there are still references to specific commits.
-
-We track `master` for the master branch and the version branch for other official branches,
-starting with `0.9.0`.
-We update the uber-project recorded SHA reference to subprojects on releases but not regularly --
-that just creates noise and is unnecessary with the `--remote` option on `submodule update`.
-In fact, `git submodule update --remote --merge` pretty much works well;
-the `git sup` alias (below) makes it even easier.
-
-On the other hand, `git status` is not very nice in the uber-project:
-it will show a "new commits" message for submodules,
-unless you're exactly at the uber-project's recorded reference.
-Ignore these.
-It will tell you if you have uncommitted changes,
-but it's not very useful for telling whether you're up to date or if you have newer changes committed
-in the subproject or in your push branch.
-If you go in to each sub-project, `git status` works better, but it can be confusing
-to track which branch each subproject is one.
-A `summary` script is provided below which solves these issues,
-showing useful status across all subprojects.
-
-
-### Pitfalls of Submodules
-
-Submodules can be confusing; if you get stuck the references at the bottom may be useful.
-You can also work [without submodules](no-submodules.html).
-
-Some of the things to be careful of are:
-
-* **Don't copy submodule directories.** This doesn't act as you'd expect;
- its `.git` record simply points at the parent project's `.git` folder,
- which in turn points back at it. So if you copy it and make changes in the copy,
- it's rather surprising where those changes actually get made.
- Worse, `git` doesn't report errors; you'll only notice it when you see files change bizarrely.
-
-* **Be careful committing in the uber-project.**
- You can update commit IDs, but if these accidentally point to an ID that isn't committed,
- everyone else sees errors.
- It's useful to do this on release (and update the target branch then also)
- and maybe occasionally at other milestones but so much at other times as these ID's
- very quickly become stale on `master`.
-
-
-### Useful Aliases
-
-This sets up variants of `pull`, `diff`, and `push` -- called `sup`, `sdiff`, and `spush` -- which act across submodules:
-
-{% highlight bash %}
-git config --global alias.sup '!git pull && git submodule update --remote --merge --recursive'
-git config --global alias.sdiff '!git diff && git submodule foreach "git diff"'
-git config --global alias.spush '!git push && git submodule foreach "git push"'
-{% endhighlight %}
-
-
-#### Getting a Summary of Submodules
-
-The `git-summary` script [here](https://gist.githubusercontent.com/ahgittin/6399a29df1229a37b092) makes working with submodules much more enjoyable,
-simply install and use `git ss` in the uber-project to see the status of each submodule:
-
-{% highlight bash %}
-curl https://gist.githubusercontent.com/ahgittin/6399a29df1229a37b092/raw/208cf4b3ec2ede77297d2f6011821ae62cf9ac0c/git-summary.sh \
- | sudo tee /usr/local/bin/git-summary
-sudo chmod 755 /usr/local/bin/git-summary
-git config --global alias.ss '!git-summary -r'
-git config --global alias.so '!git-summary -r -o'
-{% endhighlight %}
-
-You'll get output such as:
-
-{% highlight bash %}
-brooklyn: master <- upstream/master (up to date)
-
-brooklyn-client: master <- upstream/master (up to date)
-
-brooklyn-dist: master <- upstream/master (up to date)
-
-brooklyn-docs: master <- upstream/master (uncommitted changes only)
- M guide/dev/code/submodules.md
-
-brooklyn-library: master <- upstream/master (up to date)
-
-brooklyn-server: master <- upstream/master (up to date)
-
-brooklyn-ui: test <- origin/test (upstream 2 ahead of master)
- > 62c553e Alex Heneveld, 18 minutes ago: WIP 2
- > 22cd0ad Alex Heneveld, 62 minutes ago: WIP 1
- ?? wip-local-untracked-file
-{% endhighlight %}
-
-If you want it to run fast, or you're offline, you can use `git so` to run in off-line mode.
-Run `git-summary --help` for more information.
-
-
-#### Other Handy Commands
-
-{% highlight bash %}
-# run a git command (eg pull) in each submodule
-git submodule foreach 'git pull'
-
-# iterate across submodules in bash, e.g. doing git status
-for x in brooklyn-* ; do pushd $x ; git status ; popd ; done
-{% endhighlight %}
-
-
-### Legacy Incubator Pull Requests
-
-If you need to apply code changes made pre-graduation, against the incubator repository,
-splitting it up into submodules, it's fairly straightforward:
-
-1. In the incubator codebase, start at its final state: `cd .../incubator-brooklyn && git checkout master && git pull`
-2. Make a branch for your merged changes: `git checkout -b my-branch-merged-master`
-3. Merge or rebase the required commits (resolving conflicts; but don't worry about commit messages): `git merge my-branch`
-4. Create a patch file: `git diff > /tmp/diff-for-my-branch`
-5. Go to the new `brooklyn` uber-project directory.
- Ensure you are at master and all subprojects updated: `cd .../brooklyn/ && git sup`
-6. Apply the patch: `patch -p1 < /tmp/diff-for-my-branch`
-7. Inspect the changes: `git ss`
-8. Test it, commit each changed project on a branch and create pull requests.
- Where applicable, record the original author(s) and message(s) in the commit.
-
-
-
-## Git Submodule References
-
-* [1] [Git SCM Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
-* [2] [Medium blog: Mastering Git Submodules](https://medium.com/@porteneuve/mastering-git-submodules-34c65e940407#.r7677prhv)
-* [3] `git submodule --help` section on `update`
-* [4] [StackOverflow: Git Submodules Branch Tag](http://stackoverflow.com/questions/1777854/git-submodules-specify-a-branch-tag/18797720#18797720)
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/guide/dev/env/index.md
----------------------------------------------------------------------
diff --git a/guide/dev/env/index.md b/guide/dev/env/index.md
deleted file mode 100644
index 8e1e422..0000000
--- a/guide/dev/env/index.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Dev Environment
-layout: website-normal
-breadcrumbs:
-- /website/documentation/index.md
-- ../index.md
-- index.md
-children:
-- maven-build.md
-- ide/
----
-
-{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/guide/dev/index.md b/guide/dev/index.md
index 4239544..79e22fd 100644
--- a/guide/dev/index.md
+++ b/guide/dev/index.md
@@ -6,8 +6,9 @@ breadcrumbs:
- /website/documentation/index.md
- /guide/dev/index.md
children:
-- code/
-- env/
+- { link: "{{ site.path.website }}/developers/code/", title: "Get the Code" }
+- env/maven-build.md
+- env/ide/
- code/structure.md
- code/tests.md
- code/licensing.md
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/website/developers/code/git-more.md
----------------------------------------------------------------------
diff --git a/website/developers/code/git-more.md b/website/developers/code/git-more.md
new file mode 100644
index 0000000..c3e634b
--- /dev/null
+++ b/website/developers/code/git-more.md
@@ -0,0 +1,290 @@
+---
+title: Get the Code
+layout: website-normal
+menu_proxy_for: index.md
+children:
+- { link: index.html, title: Basics }
+- { section: Set Up Forks }
+- { section: Multi-Project Changes }
+- { section: How We Use Branches, title: Branches }
+- { section: About Submodules, title: Submodules }
+- { section: Not Using Submodules }
+- { section: Useful Aliases and Commands, title: Git Aliases }
+- { section: Legacy Incubator Pull Requests, title: Incubator PRs }
+---
+
+## Set Up Forks
+
+If you're contributing or working a lot on a feature,
+you'll probably want your own forks and a slightly different git remote setup.
+
+You can create forks of each Brooklyn repo [in the GitHub UI](https://github.com/apache?query=brooklyn)
+or, if you have the command-line tool `hub` ([described here](https://github.com/github/hub), or `sudo npm install -g hub`),
+by running this command:
+
+{% highlight bash %}
+hub fork; git submodule foreach 'hub fork'
+{% endhighlight %}
+
+The [Get the Code: Basics](index.html) page described how to retrieve the upstream repos,
+but it gave those remotes the name `origin`.
+When using forks, `upstream` is a more accurate name.
+You can rename the origin remotes with:
+
+{% highlight bash %}
+git remote rename origin upstream; git submodule foreach 'git remote rename origin upstream'
+{% endhighlight %}
+
+You'll now likely want to add the remote `origin` for your fork:
+
+{% highlight bash %}
+if [ -z "$GITHUB_ID" ] ; then echo -n "Enter your GitHub ID id: " ; read GITHUB_ID ; fi
+git remote add origin git@github.com:${GITHUB_ID}/apache
+git submodule foreach 'git remote add origin git@github.com:${GITHUB_ID}/${name}'
+{% endhighlight %}
+
+And if you created the fork in the GitHub UI, you may want to create a remote named by your
+GitHub ID as well (if you used `hub` it will have done it for you):
+
+{% highlight bash %}
+if [ -z "$GITHUB_ID" ] ; then echo -n "Enter your GitHub ID id: " ; read GITHUB_ID ; fi
+git remote add ${GITHUB_ID} git@github.com:${GITHUB_ID}/apache
+git submodule foreach 'git remote add ${GITHUB_ID} git@github.com:${GITHUB_ID}/${name}'
+{% endhighlight %}
+
+You probably also want the default `push` target to be your repo in the `origin` remote:
+
+{% highlight bash %}
+git config remote.pushDefault origin; git submodule foreach 'git config remote.pushDefault origin'
+{% endhighlight %}
+
+Optionally, if you're interested in reviewing pull requests,
+you may wish to have `git` automatically check out PR branches:
+
+{% highlight bash %}
+git config --local --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*'
+git submodule foreach "git config --local --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*'"
+git pull ; git submodule foreach 'git pull'
+{% endhighlight %}
+
+And also optionally, to set up the official Apache repo as a remote ---
+useful if GitHub is slow to update (and required if you're a committer):
+
+{% highlight bash %}
+git remote add apache-git https://git-wip-us.apache.org/repos/asf/brooklyn
+git submodule foreach 'git remote add apache-git https://git-wip-us.apache.org/repos/asf/${name}'
+{% endhighlight %}
+
+
+**That's it.** Test that it's all working by browsing the submodules and issuing `git remote -v` and `git pull` commands. Also see the aliases below.
+
+To work on code in a branch, in any of the submodules, you can simply do the following:
+
+{% highlight bash %}
+% git branch my-new-feature-branch upstream/master
+% git checkout my-new-feature-branch
+(make some commits)
+% git push
+To https://github.com/your_account/brooklyn.git
+ * [new branch] my-new-feature-branch -> my-new-feature-branch
+{% endhighlight %}
+
+Note how the branch is tracking `upstream/master` for the purpose of `git pull`,
+but a `git push` goes to the fork.
+When you're finished, don't forget to go to the UI of your repo to open a pull request.
+
+
+## Multi-Project Changes
+
+Cross-project changes will require multiple PRs:
+try to minimise these, especially where one depends on another,
+and especially especially where two depend on each other -- that is normally a sign of broken backwards compatibility!
+Open the PRs in dependency order and assist reviewers by including the URLs of any upstream dependency PRs
+in the dependent PR to help reviewers
+(dependency PRs will then include a "mention" comment of the dependent PR).
+
+For information on reviewing and committing PRs, see [the committer's guide]({{site.path.website}}/developers/committers/merging-contributed-code.html).
+
+
+## How We Use Branches
+
+### History, Tags, and Workflow
+
+There are branches for each released version and tags for various other milestones.
+
+As described in more detail [here](git-more.html#how-we-use-branches),
+we primarily use submodule remote branch tracking
+rather than submodule SHA1 ID's.
+
+The history prior to `0.9.0` is imported from the legacy `incubator-brooklyn` repo for reference and history only.
+Visit that repo to build those versions; they are not intended to build here.
+(Although this works:
+`mkdir merged ; for x in brooklyn-* ; do pushd $x ; git checkout 0.8.0-incubating ; cp -r * ../merged ; popd ; cd merged ; mvn clean install`.)
+
+
+### Tracking Branches
+
+Our submodules track **branches**, rather than specific commits,
+although due to the way `git` works there are still references to specific commits.
+
+We track `master` for the master branch and the version branch for other official branches,
+starting with `0.9.0`.
+We update the uber-project recorded SHA reference to subprojects on releases but not regularly --
+that just creates noise and is unnecessary with the `--remote` option on `submodule update`.
+In fact, `git submodule update --remote --merge` pretty much works well;
+the `git sup` alias (below) makes it even easier.
+
+On the other hand, `git status` is not very nice in the uber-project:
+it will show a "new commits" message for submodules,
+unless you're exactly at the uber-project's recorded reference.
+Ignore these.
+It will tell you if you have uncommitted changes,
+but it's not very useful for telling whether you're up to date or if you have newer changes committed
+in the subproject or in your push branch.
+If you go in to each sub-project, `git status` works better, but it can be confusing
+to track which branch each subproject is one.
+A `summary` script is provided below which solves these issues,
+showing useful status across all subprojects.
+
+
+## About Submodules
+
+Submodules can be confusing; if you get stuck the info and references in this section may be useful.
+You can also work [without submodules](#not-using-submodules).
+
+
+### Pitfalls of Submodules
+
+Some of the things to be careful of are:
+
+* **Don't copy submodule directories.** This doesn't act as you'd expect;
+ its `.git` record simply points at the parent project's `.git` folder,
+ which in turn points back at it. So if you copy it and make changes in the copy,
+ it's rather surprising where those changes actually get made.
+ Worse, `git` doesn't report errors; you'll only notice it when you see files change bizarrely.
+
+* **Be careful committing in the uber-project.**
+ You can update commit IDs, but if these accidentally point to an ID that isn't committed,
+ everyone else sees errors.
+ It's useful to do this on release (and update the target branch then also)
+ and maybe occasionally at other milestones but so much at other times as these ID's
+ very quickly become stale on `master`.
+
+
+### Git Submodule References
+
+* [1] [Git SCM Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+* [2] [Medium blog: Mastering Git Submodules](https://medium.com/@porteneuve/mastering-git-submodules-34c65e940407#.r7677prhv)
+* [3] `git submodule --help` section on `update`
+* [4] [StackOverflow: Git Submodules Branch Tag](http://stackoverflow.com/questions/1777854/git-submodules-specify-a-branch-tag/18797720#18797720)
+
+
+## Not Using Submodules
+
+If you don't want to use submodules, you can clone everything as top-level projects with the following:
+
+{% highlight bash %}
+mkdir apache-brooklyn
+cd apache-brooklyn
+git clone http://github.com/apache/brooklyn/
+git clone http://github.com/apache/brooklyn-ui/
+git clone http://github.com/apache/brooklyn-server/
+git clone http://github.com/apache/brooklyn-client/
+git clone http://github.com/apache/brooklyn-docs/
+git clone http://github.com/apache/brooklyn-library/
+git clone http://github.com/apache/brooklyn-dist/
+{% endhighlight %}
+
+
+With one symbolic link in the root `apache-brooklyn/` dir, you can then use a normal `mvn` workflow:
+
+{% highlight bash %}
+ln -s brooklyn/pom.xml .
+mvn clean install
+{% endhighlight %}
+
+
+With minor changes you can follow the instructions for creating forks and getting all updates
+elsewhere on this page.
+
+
+
+## Useful Aliases and Commands
+
+This sets up variants of `pull`, `diff`, and `push` -- called `sup`, `sdiff`, and `spush` -- which act across submodules:
+
+{% highlight bash %}
+git config --global alias.sup '!git pull && git submodule update --remote --merge --recursive'
+git config --global alias.sdiff '!git diff && git submodule foreach "git diff"'
+git config --global alias.spush '!git push && git submodule foreach "git push"'
+{% endhighlight %}
+
+
+#### Getting a Summary of Submodules
+
+The `git-summary` script [in the brooklyn-dist/scripts](https://github.com/apache/brooklyn-dist/tree/master/scripts) makes
+working with submodules much more enjoyable.
+Follow the `README` in that directory to add those scripts to your path, and then set up the following git aliases:
+
+{% highlight bash %}
+curl https://gist.githubusercontent.com/ahgittin/6399a29df1229a37b092/raw/208cf4b3ec2ede77297d2f6011821ae62cf9ac0c/git-summary.sh \
+ | sudo tee /usr/local/bin/git-summary
+sudo chmod 755 /usr/local/bin/git-summary
+git config --global alias.ss '!git-summary -r'
+git config --global alias.so '!git-summary -r -o'
+{% endhighlight %}
+
+Then `git ss` will give output such as:
+
+{% highlight bash %}
+brooklyn: master <- upstream/master (up to date)
+
+brooklyn-client: master <- upstream/master (up to date)
+
+brooklyn-dist: master <- upstream/master (up to date)
+
+brooklyn-docs: master <- upstream/master (uncommitted changes only)
+ M guide/dev/code/submodules.md
+
+brooklyn-library: master <- upstream/master (up to date)
+
+brooklyn-server: master <- upstream/master (up to date)
+
+brooklyn-ui: test <- origin/test (upstream 2 ahead of master)
+ > 62c553e Alex Heneveld, 18 minutes ago: WIP 2
+ > 22cd0ad Alex Heneveld, 62 minutes ago: WIP 1
+ ?? wip-local-untracked-file
+{% endhighlight %}
+
+The command `git so` does the same thing without updating remotes.
+Use it if you want it to run fast, or if you're offline.
+For more information un `git-summary --help`.
+
+
+#### Other Handy Commands
+
+{% highlight bash %}
+# run a git command (eg pull) in each submodule
+git submodule foreach 'git pull'
+
+# iterate across submodules in bash, e.g. doing git status
+for x in brooklyn-* ; do pushd $x ; git status ; popd ; done
+{% endhighlight %}
+
+
+## Legacy Incubator Pull Requests
+
+If you need to apply code changes made pre-graduation, against the incubator repository,
+splitting it up into submodules, it's fairly straightforward:
+
+1. In the incubator codebase, start at its final state: `cd .../incubator-brooklyn && git checkout master && git pull`
+2. Make a branch for your merged changes: `git checkout -b my-branch-merged-master`
+3. Merge or rebase the required commits (resolving conflicts; but don't worry about commit messages): `git merge my-branch`
+4. Create a patch file: `git diff > /tmp/diff-for-my-branch`
+5. Go to the new `brooklyn` uber-project directory.
+ Ensure you are at master and all subprojects updated: `cd .../brooklyn/ && git sup`
+6. Apply the patch: `patch -p1 < /tmp/diff-for-my-branch`
+7. Inspect the changes: `git ss`
+8. Test it, commit each changed project on a branch and create pull requests.
+ Where applicable, record the original author(s) and message(s) in the commit.
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/website/developers/code/index.md
----------------------------------------------------------------------
diff --git a/website/developers/code/index.md b/website/developers/code/index.md
new file mode 100644
index 0000000..40590ca
--- /dev/null
+++ b/website/developers/code/index.md
@@ -0,0 +1,82 @@
+---
+title: Get the Code
+layout: website-normal
+children:
+- { path: git-more.md, title: "Forks, Git-Fu, and More" }
+---
+
+## The Basics
+
+The Apache Brooklyn source code is available at [GitHub apache/brooklyn](http://github.com/apache/brooklyn),
+together with many [`brooklyn-*` sub-module projects](https://github.com/apache?query=brooklyn).
+Checkout and build all the submodules with:
+
+{% highlight bash %}
+git clone http://github.com/apache/brooklyn/
+cd brooklyn
+git submodule init
+git submodule update --remote --merge --recursive
+
+mvn clean install
+{% endhighlight %}
+
+This will produce an artifact in `brooklyn-dist/dist/brooklyn-dist-0.9.0-SNAPSHOT-dist.tar.gz` <!-- BROOKLYN_VERSION -->
+which you can use [in the usual way]({{ site.path.guide }}/start/running.html).
+Some options which may be useful:
+
+* Use `--depth 1` with `git clone` to skip the history (much faster but your `git log` will be incomplete)
+* Use `-DskipTests` with `mvn` to skip tests (again much faster but it won't catch failures)
+* See below if you don't want to use submodules
+
+Thereafter to update the code in submodules, we strongly recommend doing this:
+
+ git pull && git submodule update --remote --merge --recursive
+
+This merges the latest upstream changes into the current branch of each sub-module on your local machine,
+giving nice errors on conflicts.
+It's fine also to do branching and pulling in each submodule,
+but running `update` without these parameters can cause chaos!
+This [page](git-more.html) elaborates on potential chaos and pitfalls,
+and it provides instructions for setting up an alias `git sup` for this command.
+
+
+### If You Can't Stand Submodules
+
+[These instructions](git-more.html#not-using-submodules) can help setting up a local environment
+which does not rely on submodules.
+
+
+### Contributing a Small Change
+
+If you're making a small change in one project, consider just using that project.
+Whether you use this uber-project or not, to [contribute](../how-to-contribute.html)
+you'll need to follow the usual fork->work->push->pull-request process.
+
+To understand where you might want to make your change,
+look at the [code structure]({{ site.path.guide }}/dev/code/structure.html).
+
+
+### Bigger and Regular Changes
+
+Regular contributors will typically have their own fork for each of the submodule projects,
+and will probably want some other settings and tips [as described here](git-more.html).
+
+
+## Next Steps
+
+* See the [detailed Brooklyn & Git guide](git-more.html) to
+ [set up forks](git-more.html#set-up-forks) or [handy git aliases](git-more.html#useful-aliases-and-commands)
+
+* Visit the [Developer Guide]({{ site.path.guide }}/dev/) has information on
+ [project structure]({{ site.path.guide }}/dev/code/structure.html),
+ [Maven setup]({{ site.path.guide }}/dev/env/maven-build.html) and more
+
+* Review [How to Contribute](../how-to-contribute.html)
+ to [file your CLA](../how-to-contribute.html#contributor-license-agreement)
+ or
+ [project structure]({{ site.path.guide }}/dev/code/structure.html),
+ [Maven setup]({{ site.path.guide }}/dev/env/maven-build.html) and more
+
+Where things aren't documented **please ask us** at
+[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/brooklyn-dev/)
+so we can remedy this!
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/website/developers/committers/merging-contributed-code.md
----------------------------------------------------------------------
diff --git a/website/developers/committers/merging-contributed-code.md b/website/developers/committers/merging-contributed-code.md
index e910e96..a21170a 100644
--- a/website/developers/committers/merging-contributed-code.md
+++ b/website/developers/committers/merging-contributed-code.md
@@ -36,7 +36,7 @@ Rules of thumb
Setting up your repository
--------------------------
-Follow [these instructions]({{site.path.guide}}/dev/code/submodules.html) to configure your local repositories.
+Follow [these instructions](../code/git-more.html) to configure your local repositories.
Make sure the canonical ASF repo is enabled as that is where you'll need to push to merge changes,
and that you are able to fetch pull-requests.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/website/developers/how-to-contribute.md
----------------------------------------------------------------------
diff --git a/website/developers/how-to-contribute.md b/website/developers/how-to-contribute.md
index 91a1d5a..551c486 100644
--- a/website/developers/how-to-contribute.md
+++ b/website/developers/how-to-contribute.md
@@ -6,7 +6,8 @@ children:
- { section: Create an Issue in Jira, title: Jira }
- { section: Contributing using GitHub, title: GitHub }
- { section: Reviews }
-- { section: Handy Places }
+- { link: code/, title: Get the Code }
+- { link: links.html, title: Handy Places }
---
Welcome and thank you for your interest in contributing to Apache Brooklyn! This guide will take you through the
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/website/developers/index.md
----------------------------------------------------------------------
diff --git a/website/developers/index.md b/website/developers/index.md
index 14dba00..5e07c87 100644
--- a/website/developers/index.md
+++ b/website/developers/index.md
@@ -2,10 +2,12 @@
layout: website-normal
title: Developers
children:
+- code/
- how-to-contribute.md
- /guide/dev/
- committers/
- code-standards.md
+- links.md
- { link: 'http://github.com/apache/brooklyn', title: 'GitHub' }
- { link: 'https://issues.apache.org/jira/browse/BROOKLYN', title: 'Bug Tracker (JIRA)' }
---
@@ -36,11 +38,12 @@ simply come say hello somewhere in the [community](../community/index.html):
- [IRC channel](../community/irc.html)
- [JIRA for bug tracking](https://issues.apache.org/jira/browse/BROOKLYN)
-Once you have some code or a blueprint you want to share,
+Then [get the code](code/).
+
+When you have a blueprint or an improvement you want to share,
there are a few instructions to note on [how to contribute](how-to-contribute.html).
If you're looking to learn more about the codebase itself,
have a look at [Developer Guide]({{ site.path.guide }}/dev/).
There are also a number of [development bookmarks](links.html) for the tools we use
(git, jenkins, jira).
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6b1b3307/website/developers/links.md
----------------------------------------------------------------------
diff --git a/website/developers/links.md b/website/developers/links.md
index ef0dbdc..324a633 100644
--- a/website/developers/links.md
+++ b/website/developers/links.md
@@ -1,7 +1,6 @@
---
layout: website-normal
-title: Development Bookmarks
-menu_proxy_for: index.md
+title: Handy Places
---
{% include fields.md %}