brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rich...@apache.org
Subject [29/36] incubator-brooklyn git commit: Cherry-pick merge of PR #389 into 0.7.0-M2-incubating-docs branch
Date Fri, 09 Jan 2015 15:39:11 GMT
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/links.md
----------------------------------------------------------------------
diff --git a/docs/dev/links.md b/docs/dev/links.md
deleted file mode 100644
index b224085..0000000
--- a/docs/dev/links.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-layout: page
-title: Development Bookmarks
-toc: ../toc.json
----
-
-
-Handy places:
-
-* **Code** is in Github at [https://github.com/brooklyncentral/brooklyn](https://github.com/brooklyncentral/brooklyn)
-
-* **Issues** are also on Github at [https://github.com/brooklyncentral/brooklyn/issues](https://github.com/brooklyncentral/brooklyn/issues)
-
-* **Maven repositories** are at [http://developers.cloudsoftcorp.com/download/maven2/](http://developers.cloudsoftcorp.com/download/maven2/) for releases 
-  and [http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/](http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/) for snapshots
-  (under ``io/brooklyn``)
-            
-* **CI server** is currently a private server managed by Cloudsoft. There is a proposal to move to CloudBees.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/tips/index.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/index.md b/docs/dev/tips/index.md
deleted file mode 100644
index e874cfa..0000000
--- a/docs/dev/tips/index.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-layout: page
-title: Miscellaneous Tips and Tricks
-toc: /toc.json
----
-
-## General Good Ways of Working
-
-* If working on something which could be contributed to Brooklyn,
-  do it in a project under the ``sandbox`` directory.
-  This means we can accept pulls more easily (as sandbox items aren't built as part of the main build)
-  and speed up collaboration.
-  
-* When debugging an entity, make sure the  [brooklyn.SSH logger](logging.html) is set to DEBUG and accessible.
- 
-* Use tests heavily!  These are pretty good to run in the IDE (once you've completed [IDE setup]({{site.url}}/dev/build/ide.html)),
-  and far quicker to spot problems than runtime, plus we get early-warning of problems introduced in the future.
-  (In particular, Groovy's laxity with compilation means it is easy to introduce silly errors which good test coverage will find much faster.)
-  
-* If you hit inexplicable problems at runtime, try clearing your Maven caches,
-  or the brooklyn-relevant parts, under ``~/.m2/repository``.
-  Also note your IDE might be recompiling at the same time as a Maven command-line build,
-  so consider turning off auto-build.
-
-
-<a name="EntityDesign"></a>
-## Entity Design Tips
-
-* Look at related entities and understand what they've done, in particular which
-  sensors and config keys can be re-used.
-  (Many are inherited from interfaces, where they are declared as constants,
-  e.g. ``Attributes`` and ``UsesJmx``.)
-  
-* Understand the location hierarchy:  software process entities typically get an ``SshMachineLocation``,
-  and use a ``*SshDriver`` to do what they need.  This will usually have a ``MachineProvisioningLocation`` parent, e.g. a
-  ``JcloudsLocation`` (e.g. AWS eu-west-1 with credentials) or possibly a ``LocalhostMachineProvisioningLocation``.
-  Clusters will take such a ``MachineProvisioningLocation`` (or a singleton list); fabircs take a list of locations.
-  Some PaaS systems have their own location model, such as ``OpenShiftLocation``.
-
-Finally, don't be shy about [talking with others]({{site.url}}/meta/contact.html), 
-that's far better than spinning your wheels (or worse, having a bad experience),
-plus it means we can hopefully improve things for other people!
-
-
-## Project Maintenance
-
-* Adding a new project may need updates to ``/pom.xml`` ``modules`` section and ``usage/all`` dependencies
- 
-* Adding a new example project may need updates to ``/pom.xml`` and ``/examples/pom.xml`` (and the documentation too!)
-

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/tips/local-artifact-repo.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/local-artifact-repo.md b/docs/dev/tips/local-artifact-repo.md
deleted file mode 100644
index 08bf08a..0000000
--- a/docs/dev/tips/local-artifact-repo.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-layout: page
-title: Prepopulating a Local Artifact Repository
-toc: /toc.json
----
-
-On occasion it can be useful to have/control/prepopulate a local repository of entity installers <small>[1]</small>.
-
-The following command (run from `~/`) may be used to sync Cloudsoft's fallback repository to the local `~/.brooklyn/repository/` folder:
-
-	wget --directory-prefix=".brooklyn/repository/" --no-parent --relative --no-host-directories --reject="index.html*" --cut-dirs=2 --recursive -e robots=off --user-agent="Brooklyn Repository Sync" http://downloads.cloudsoftcorp.com/brooklyn/repository/
-
-Brooklyn's default search behaviour for installation artifacts is as follows:
-
-1.  The local `~/.brooklyn/repository/` folder.
-2.	The entity's installer's public download url (or an overridden url if one has been specified).
-3.	Cloudsoft's fallback repository.
-
-Cloudsoft's fallback repository <small>[2]</small> contains many of the installation artifacts used by current Brooklyn entities. 
-
-It is intended to prevent problems occurring when the public url for an installer changes (e.g. when several new versions of MySQL have been released). It is provided on an as-is and as-available basis.
-
-If you use this command to create a local repository, please respect the `--user-agent`. In future this will allow Cloudsoft to easily filter repository syncing behaviour from  fallback behaviour, allowing out-of-date entities to be more easily identified and updated. 
-
-<br />
-<small>
-<ol>
-<li>For example, when establishing a local cache or enterprise golden source, or when developing Brooklyn while offline, in planes, trains and automobiles, or other such situations of exemplary derring-do <small>[3]</small>.</li> 
-<li><a href="http://downloads.cloudsoftcorp.com/brooklyn/repository/">downloads.cloudsoftcorp.com/brooklyn/repository</a></li>
-<li>This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.</li>
-</ol>
-</small>

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/tips/logging.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/logging.md b/docs/dev/tips/logging.md
deleted file mode 100644
index 927fd0b..0000000
--- a/docs/dev/tips/logging.md
+++ /dev/null
@@ -1,140 +0,0 @@
----
-layout: page
-title: Logging
-toc: /toc.json
----
-
-## Logging: A Quick Overview
-
-For logging, we use **logback** which implements the slf4j API.
-This means you can use any slf4j compliant logging framework,
-with a default configuration which just works out of the box
-and bindings to the other common libraries (``java.util.logging``, ``log4j``, ...)
-if you prefer one of those.
-
-To use:
-
-* **Users**:
-If using a brooklyn binary installation, simply edit the ``logback.xml``
-or ``logback-custom.xml`` supplied in the archive, sometimes in a ``conf/``
-directory.
-
-* **Developers**:
-When setting up a new project, if you want logging it is recommended to include 
-the ``brooklyn-logback-xml`` project as an *optional* and *provided* maven dependency, 
-and then to put custom logging configuration in either ``logback-custom.xml`` or ``logback-main.xml``, 
-as described below.
-
-
-## Customizing Your Logging
-
-The project ``brooklyn-logback-xml`` supplies a ``logback.xml`` configuration,
-with a mechanism which allows it to be easily customized, consumed, and overridden.
-You may wish to include this as an *optional* dependency so that it is not forced
-upon downstream projects.  This ``logback.xml`` file supplied contains just one instruction,
-to include ``logback-main.xml``, and that file in turn includes:
-
-* ``logback-custom.xml``
-* ``brooklyn/logback-appender-file.xml``
-* ``brooklyn/logback-appender-stdout.xml``
-* ``brooklyn/logback-logger-excludes.xml``
-* ``brooklyn/logback-debug.xml``
-   
-For the most common customizations, simply create a ``logback-custom.xml`` on your classpath
-(ensuring it is loaded *before* brooklyn classes in classpath ordering in the pom)
-and supply your customizations there:  
-
-{% highlight xml %}
-<included>
-    <!-- filename to log to -->           
-    <property name="logging.basename" scope="context" value="acme-app" />
-    
-    <!-- additional loggers -->
-    <logger name="com.acme.app" level="DEBUG"/>
-</included>
-{% endhighlight %}
-
-For other configuration, you can override individual files listed above.
-For example:
-
-* To remove debug logging, create a trivial ``brooklyn/logback-debug.xml``, 
-  containing simply ``<included/>``.
-* To customise stdout logging, perhaps to give it a threshhold WARN instead of INFO,
-  create a ``brooklyn/logback-appender-stdout.xml`` which defines an appender STDOUT.
-* To discard all brooklyn's default logging, create a ``logback-main.xml`` which 
-  contains your configuration. This should look like a standard logback
-  configuration file, except it should be wrapped in ``<included>`` XML tags rather
-  than ``<configuration>`` XML tags (because it is included from the ``logback.xml``
-  which comes with ``brooklyn-logback-xml``.)
-
-You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``.
-If you do, logback will detect multiple files with that name and will scream at you.
-If you wish to supply your own ``logback.xml``, do **not** include ``brooklyn-logback-xml``.
-(Alternatively you can include a ``logback.groovy`` which causes logback to ignore ``logback.xml``.)
-
-You can set a specific logback config file to use with:
-
-{% highlight bash %}
--Dlogback.configurationFile=/path/to/config.xml
-{% endhighlight %}
-
-
-## Assemblies
-
-When building an assembly, it is recommended to create a ``conf/logback.xml`` which 
-simply includes ``logback-main.xml`` (which comes from the classpath).  Users of the assembly
-can then edit the ``logback.xml`` file in the usual way, or they can plug in to the configuration 
-mechanisms described above, by creating files such as ``logback-custom.xml`` under ``conf/``.
-
-Including ``brooklyn-logback-xml`` as an *optional* and *provided* dependency means everything
-should work correctly in IDE's but it will not include the extra ``logback.xml`` file in the assembly.
-(Alternatively if you include the ``conf/`` dir in your IDE build, you should exclude this dependency.)
-
-With this mechanism, you can include ``logback-custom.xml`` and/or other files underneath 
-``src/main/resources/`` of a project, as described above (for instance to include custom
-logging categories and define the log file name) and it should get picked up, 
-both in the IDE and in the assembly.   
- 
-
-## Tests
-
-Brooklyn projects ``test`` scope includes the ``brooklyn-utils-test-support`` project
-which supplies a ``logback-test.xml``. logback uses this file in preference to ``logback.xml``
-when available (ie when running tests). However the ``logback-test.xml`` Brooklyn uses
-includes the same ``logback-main.xml`` call path above, so your configurations should still work.
-
-The only differences of the ``logback-test.xml`` configuration is that:
-
-* Debug logging is included for all Brooklyn packages
-* The log file is called ``brooklyn-tests.log`` 
-
-
-## Caveats
-
-* logback uses SLF4J version 1.6 which is **not compatible** with 1.5.x. 
-  If you have dependent projects using 1.5.x (such as older Grails) things may break.
-
-* If you're not getting the logging you expect in the IDE, make sure 
-  ``src/main/resources`` is included in the classpath.
-  (In eclipse, right-click the project, the Build Path -> Configure,
-  then make sure all dirs are included (All) and excluded (None) -- 
-  ``mvn clean install`` should do this for you.)
-
-* You may find that your IDE logs to a file ``brooklyn-tests.log`` 
-  if it doesn't distinguish between test build classpaths and normal classpaths.
-
-* Logging configuration using file overrides such as this is very sensitive to
-  classpath order. To get a separate `brooklyn-tests.log` file during testing,
-  for example, the `brooklyn-test-support` project with scope `test` must be
-  declared as a dependency *before* `brooklyn-logback-includes`, due to the way
-  both files declare `logback-appender-file.xml`.
-  
-* Similarly note that the `logback-custom.xml` file is included *after* 
-  logging categories and levels are declared, but before appenders are declared,
-  so that logging levels declared in that file dominate, and that 
-  properties from that file apply to appenders.
-
-* Finally remember this is open to improvement. It's the best system we've found
-  so far but we welcome advice. In particular if it could be possible to include
-  files from the classpath with wildcards in alphabetical order, we'd be able
-  to remove some of the quirks listed above (though at a cost of some complexity!).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/tips/release.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/release.md b/docs/dev/tips/release.md
deleted file mode 100644
index 1360f46..0000000
--- a/docs/dev/tips/release.md
+++ /dev/null
@@ -1,286 +0,0 @@
----
-layout: page
-title: Release Process
-toc: /toc.json
----
-
-<!--
-TODO
-
-vote required?  see governance.
-
-
-     branch-twice-then-reversion-twice
-     e.g. from master=1.0.0_SNAPSHOT we will go to
-          create branch: v1.0.0_SNAPSHOT
-          reversion master:  1.1.0_SNAPSHOT
-          create branch and reversion:  v1.0.0_RC1, v1.0.0_SNAPSHOT
-     describe scripts for releasing
-     docs
-
-update version, using scripts
-
-push examples to repo
-
-push docs to branch and publish
-
--->
-
-Brooklyn is published to two locations:
-
-* Sonatype, for snapshots and for staging releases
-* Maven Central, for full (GA and milestone) releases
-
-Brooklyn artifacts are generally downloaded from:
-
-1. [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.brooklyn%22), 
-   and (http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.brooklyn%22) for pre 0.7.0 versions
-2. [Apache](https://repository.apache.org/index.html#nexus-search;quick~org.apache.brooklyn),
-2. [Sonatype](https://oss.sonatype.org/index.html#nexus-search;quick~io.brooklyn) for pre 0.7.0 versions
-3. [GitHub](https://github.com/apache/incubator-brooklyn).
-
-
-To publish:
-
-* a snapshot release:
-	* mvn deploy to Sonatype
-	* (optional) publish versioned docs to brooklyncentral.github.com project
-* a (milestone) release:
-	* same as above, but with some git versioning 
-	* deploy to Sonatype, then release to Maven Central
-	* deploy a version branch to brooklyn-examples 
-	* deploy (or update) versioned docs
-* a major release:
-	* same as above, and
-	* in addition to versioned examples,  update brooklyn-examples master to match the current (stable) release
-	* in addition to versioned docs, publish full (front page) docs to brooklyncentral.github.com project
-	* bump the snapshot version in brooklyn master to the next release
-
-
-	
-## Configuration 
-
-Your .m2/settings.xml must be configured with the right credentials for Sonatype
-
-  	<servers>
-	...
-		<server>
-			<username> ... </username>
-			<password> ... </password>
-			<id>sonatype-nexus-snapshots</id>
-		</server>
-		<server>
-			<username> ... </username>
-			<password> ... </password>
-			<id>sonatype-nexus-staging</id>
-		</server>
-	...
-	</servers>
-You must be configured to sign artifacts using PGP.
-
-If this is the first time you have used Sonatype, the [Sonatype - Maven Usage Guide](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide) is required reading.  
-
-The code snippets below use the following variables:
-{% highlight bash %}
-
-export BROOKLYN_DIR=/path/to/brooklyncentral-brooklyn
-export EXAMPLES_DIR=/path/to/brooklyncentral-brooklyn-examples
-export SITE_DIR=/path/to/brooklyncentral-brooklyncentral.github.com
-
-export SNAPSHOT_VERSION=0.6.0-SNAPSHOT
-export RELEASE_VERSION=0.6.0-M1
-{% endhighlight %}
-
-
-## Preparing a Snapshot Release
-
-### Deploy to Sonatype
-
-Execute the following:
-{% highlight bash %}
-mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
-{% endhighlight %}
-
-### (Option) Publish snapshot docs.
-
-(Only required if there have been significant changes to docs or java docs.)
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-git checkout master
-
-if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
-
-# Build the docs
-_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
-
-# Wipe any previous edition of the same version, replacing with new build.
-rm -rf $SITE_DIR/v/$SNAPSHOT_VERSION
-mkdir $SITE_DIR/v/$SNAPSHOT_VERSION
-cp -r _site/* $SITE_DIR/v/$SNAPSHOT_VERSION/
-
-# and push, causing GitHub to republish with updated /v/$SNAPSHOT_VERSION/
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated version docs for version $SNAPSHOT_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-
-
-## Preparing a (Milestone) Release
-
-### Prepare a Release Branch
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR
-git checkout -b $RELEASE_VERSION
-usage/scripts/change-version.sh $SNAPSHOT_VERSION $RELEASE_VERSION
-git commit -a -m "Changed version to $RELEASE_VERSION"
-git push -u upstream $RELEASE_VERSION
-
-{% endhighlight %}
-
-### Deploy to Sonatype, and Close the repo.
-
-{% highlight bash %}
-mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
-{% endhighlight %}
-
-* Go to [oss.sonatype.org ... #stagingRepositories](https://oss.sonatype.org/index.html#stagingRepositories) (again, need credentials)
-* 'Close' the repo
-* Email the closed repo address to brooklyn-dev list, have people download and confirm it works.
-
-### Update the brooklyn-examples repo's version Branch
-
-{% highlight bash %}
-
-cd $EXAMPLES_DIR
-
-pushd $BROOKLYN_DIR
-git checkout $RELEASE_VERSION
-popd
-
-if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
-git checkout master
-git checkout -b $RELEASE_VERSION
-rm -rf *
-cp -r $BROOKLYN_DIR/examples/* .
-rm -rf target
-git add -A
-git commit -m "branch for $RELEASE_VERSION"
-git push -u origin $RELEASE_VERSION
-
-{% endhighlight %}
-
-
-### Update the Versioned Docs
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-git checkout $RELEASE_VERSION
-
-if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
-
-# Build the docs
-_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
-
-# Wipe any previous edition of the same version, replacing with new build.
-rm -rf $SITE_DIR/v/$RELEASE_VERSION
-mkdir $SITE_DIR/v/$RELEASE_VERSION
-cp -r _site/* $SITE_DIR/v/$RELEASE_VERSION/
-
-# and push, causing GitHub to republish with updated /v/$RELEASE_VERSION/
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated version docs for version $RELEASE_VERSION"
-git push
-popd
-
-{% endhighlight %}
-	
-## Preparing a Full Release
-
-Complete *all* above steps.
-
-### Deploy to Maven Central
-
-* Confirm that the closed Sonatype repo has no errors
-* Return to [Sonatype: Staging Repositories](https://oss.sonatype.org/index.html#stagingRepositories)
-* 'Release' the repo
-
-### Deploy the Examples master branch.
-
-{% highlight bash %}
-
-cd $EXAMPLES_DIR
-
-pushd $BROOKLYN_DIR
-git checkout $RELEASE_VERSION
-popd
-
-if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
-git checkout master
-rm -rf *
-cp -r $BROOKLYN_DIR/examples/* .
-rm -rf target
-git add -A
-git commit -m "Updated to $RELEASE_VERSION"
-git push -u origin master
-
-{% endhighlight %}
-
-### Update the brooklyn.io Front Page Version
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-
-pushd $SITE_DIR
-# remove old root files, but not the previous version in /v/
-if [ -f start/index.html ] ; then
-  for x in * ; do if [[ $x != "v" ]] ; then rm -rf $x ; fi ; done
-else
-  echo IN WRONG DIRECTORY $SITE_DIR - export SITE_DIR to continue
-  exit 1
-fi
-popd
-
-# re-build for hosting at / rather than at /v/VERSION/
-_scripts/build.sh --url "" || { echo "failed to build docs" ; exit 1 ; }
-
-# copy to site dir
-cp -r _site/* $SITE_DIR/
-
-# and git push
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated root docs for version $RELEASE_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-
-### Announce
-* Email the Dev and Users mailing lists.
-* Tweet from [@brooklyncentral](https://twitter.com/brooklyncentral)
-
-### Update Snapshot Version
-
-{% highlight bash %}
-
-export NEW_SNAPSHOT_VERSION=0.7.0-SNAPSHOT
-
-cd $BROOKLYN_DIR
-git checkout master
-usage/scripts/change-version.sh $SNAPSHOT_VERSION $NEW_SNAPSHOT_VERSION
-git commit -a -m "Changed version to $NEW_SNAPSHOT_VERSION"
-git push -u upstream master
-
-{% endhighlight %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/tips/standards.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/standards.md b/docs/dev/tips/standards.md
deleted file mode 100644
index 8ca9181..0000000
--- a/docs/dev/tips/standards.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-layout: page
-title: Code Standards
-toc: /toc.json
----
-
-Without being too restrictive about how you have to code as part of Brooklyn,
-there are some style points that really make life easier when sharing code
-among ourselves:
-
-* Use spaces (not tabs!) with 4 spaces indentation
-* Keep line length <=128
-* Don't reformat code or organize imports unless there's very good
-  reason (this makes history and merges much harder)
-

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/tips/toc.json
----------------------------------------------------------------------
diff --git a/docs/dev/tips/toc.json b/docs/dev/tips/toc.json
deleted file mode 100644
index 0be0aba..0000000
--- a/docs/dev/tips/toc.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-{ "title": "Miscellany",
-  "file": "{{ site.url }}/dev/tips/index.html" },
-{ "title": "Logging",
-  "file": "{{ site.url }}/dev/tips/logging.html" },
-{ "title": "Code Standards",
-  "file": "{{ site.url }}/dev/tips/standards.html" },
-{ "title": "Local Artifact Repo",
-  "file":  "{{ site.url }}/dev/tips/local-artifact-repo.html" },
-{ "title": "Updating Docs",
-  "file":  "{{ site.url }}/dev/tips/update-docs.html" },
-{ "title": "Release Process",
-  "file":  "{{ site.url }}/dev/tips/release.html" }
-]

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/tips/update-docs.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/update-docs.md b/docs/dev/tips/update-docs.md
deleted file mode 100644
index 3c9721a..0000000
--- a/docs/dev/tips/update-docs.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-layout: page
-title: Updating the Docs
-toc: /toc.json
----
-
-The Brooklyn docs live in the **docs** project in the Brooklyn codebase.
-It's built using standard jekyll/markdown with a few extensions.
-
-
-## Jekyll
-
-Firstly, install Pygments (used for source code highlighting):
-
-    sudo easy_install Pygments
-
-Next, install Jekyll and the other Ruby Gems that we need:
-
-    bundle install
-
-Then, in the `docs/` directory, run:
-
-    ./_scripts/jekyll-debug.sh 
-    
-Visit [http://localhost:4000/](http://localhost:4000/) and you should see the documentation.
-
-
-## Extensions
-
-In addition to the standard pygments plugin for code-highlighting,
-we use some custom Jekyll plugins (in the `_plugins` dir) to:
-
-* include markdown files inside other files 
-  (see, for example, the `*.include.md` files which contain text
-  which is used in multiple other files)
-* parse JSON which we can loop over in our markdown docs
-* trim whitespace of ends of variables
-
-Using JSON table-of-contents files (`toc.json`) is our lightweight solution
-to the problem of making the site structure navigable (the menus at left).
-If you add a page, simply add the file (with full path from project root)
-and a title to the toc.json in that directory, and it will get included
-in the menu.  You can also configure a special toc to show on your page,
-if you wish, by setting the toc variable in the header.
-Most pages declare the "page" layout (`_layouts/page.html`) which builds
-a menu in the left side-bar (`_includes/sidebar.html`) using the JSON --
-and automatically detecting which page is active. 
- 
-
-## Publishing
-
-Because GitHub don't run plugins (they run with the `--safe` option),
-the site is built off-line and uploaded to github, where the documentation is hosted.
-
-This makes the process a little more tedious, but it does have the advantage 
-that the documentation lives right in the Brooklyn project,
-easy to open alongside the code inside your IDE.
-
-The off-line build can be done using `/docs/_scripts/build.sh`,
-including both jekyll markdown documentation and Brooklyn javadoc,
-with the result of this copied to the `brooklyncentral/brooklyncentral.github.com` 
-github project (as per the GitHub pages documentation).
-[brooklyn.io](http://brooklyn.io) is CNAMEd to [brooklyncentral.github.com](brooklyncentral.github.com)
-for convenience.
-
-The latest stable version typically lives in the root of the `brooklyncentral.github.com` project.
-Archived versions are kept under `/v/*` with logic in the markdown for 
-[meta/versions]({{ site.url }}/meta/versions.html) to link to related versions.  
-Additional instructions and scripts for automating the installs can be found in `/docs/_scripts/`.
-

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/dev/toc.json
----------------------------------------------------------------------
diff --git a/docs/dev/toc.json b/docs/dev/toc.json
deleted file mode 100644
index f22e840..0000000
--- a/docs/dev/toc.json
+++ /dev/null
@@ -1,26 +0,0 @@
-[
-{ "title": "The Code",
-  "file": "{{ site.url }}/dev/code/index.html",
-  "exclude": true,
-  "children": {% readj ./code/toc.json %} },
-{ "title": "Build and Test",
-  "file": "{{ site.url }}/dev/build/index.html",
-  "exclude": true,
-  "children": {% readj ./build/toc.json %} },
-{ "title": "Tips and Tricks",
-  "file": "{{ site.url }}/dev/tips/index.html",
-  "exclude": true,
-  "children": {% readj ./tips/toc.json %} },
-{ "title": "Links",
-  "file": "{{ site.url }}/dev/links.html",
-  "children": [
-    { "title": "Github repo",
-      "file": "https://github.com/brooklyncentral/" },
-    { "title": "Github issues",
-      "file": "https://github.com/brooklyncentral/brooklyn/issues" },
-    { "title": "Maven snapshots",
-      "file": "http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/io/brooklyn/" }      
-  ] },
-{ "title": "How to Contribute",
-  "file": "{{ site.url }}/dev/how-to-contrib.html" }
-]

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/build/developers-catalog.xml
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/developers-catalog.xml b/docs/guide/dev/build/developers-catalog.xml
new file mode 100644
index 0000000..3afe052
--- /dev/null
+++ b/docs/guide/dev/build/developers-catalog.xml
@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<catalog>
+    <name>Brooklyn Developers Catalog</name>
+
+	<template type="io.cloudsoft.cloudera.SampleClouderaManagedCluster" name="Cloudera CDH4">
+		<description>Launches Cloudera Distribution for Hadoop Manager with a Cloudera Manager and an initial cluster of 4 CDH nodes
+		(resizable) and default services including HDFS, MapReduce, and HBase</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cloudera-icon.jpeg</iconUrl>
+	</template>
+	
+	<template type="io.cloudsoft.mapr.MyM3App" name="M3 Cluster">
+		<description>Map Reduce using MapR</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/mapr-icon.png</iconUrl>
+	</template>
+	
+	<template type="brooklyn.demo.SimpleMongoDBReplicaSet" name="Simple MongoDB replica set">
+        <description>Launches a MongoDB replica set</description>
+        <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/mongo-db-icon.jpeg</iconUrl>
+    </template>
+    
+	<template type="brooklyn.example.cloudfoundry.MovableCloudFoundryClusterExample" name="Stackato Movable CloudFoundry Cluster Example">
+		<description>Brooklyn Stackato</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/stackato-icon.jpeg</iconUrl>
+	</template>
+	
+	<template type="brooklyn.example.cloudfoundry.MovableElasticWebAppCluster" name="Stackato Movable Elastic Web Cluster">
+		<description>Brooklyn Stackato</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/stackato-icon.jpeg</iconUrl>
+	</template>
+	
+	<template type="io.cloudsoft.socialapps.drupal.examples.BasicDrupalApp" name="Basic Drupal App">
+		<description>Brooklyn Social Apps - Basic. (Requires Debian)</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/drupal-icon.png</iconUrl>
+	</template>
+	
+	<template type="io.cloudsoft.socialapps.drupal.examples.ClusteredDrupalApp" name="Clustered Drupal App">
+		<description>Brooklyn Social Apps - Cluster. (Requires Debian)</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/drupal-text-icon.png</iconUrl>
+	</template> 
+    
+    <template type="brooklyn.extras.cloudfoundry.CloudFoundryJavaClusterExample" name="Cloud Foundry Web App">
+		<description>Deploys a web application to a Cloud Foundry target</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cloud-foundry-logo-icon.png</iconUrl>
+	</template>
+	
+	<template type="brooklyn.demo.SimpleRedisCluster" name="Redis Cluster">
+		<description>Launches a Redis cluster</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/redis-sq-icon.png</iconUrl>
+	</template>
+	
+    <template type="brooklyn.demo.SimpleCassandraCluster" name="Cassandra Cluster">
+		<description>Launches a Cassandra cluster</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cassandra-sq-icon.jpg</iconUrl>
+	</template>
+	
+	<template type="brooklyn.demo.SimpleCouchDBCluster" name="CouchDB Cluster">
+		<description>Launches a CouchDB cluster</description>
+		<iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/couchdb-logo-icon.png</iconUrl>
+	</template>
+
+    <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo 2: GeoDNS Web Fabric DB">
+      <description>Deploys a demonstration web application to JBoss clusters around the world</description>
+      <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat-icon.png</iconUrl>
+    </template>
+
+    <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo 1: Web Cluster with DB">
+      <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description>
+      <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat-icon.png</iconUrl>
+    </template>
+    
+    
+    <classpath> 
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-M2-incubating/brooklyn-example-simple-web-cluster-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->   
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-M2-incubating/brooklyn-example-global-web-fabric-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->        
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-M2-incubating/brooklyn-example-global-web-fabric-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-portable-cloudfoundry/0.7.0-M2-incubating/brooklyn-example-portable-cloudfoundry-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-M2-incubating/brooklyn-example-simple-web-cluster-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.7.0-M2-incubating/brooklyn-example-hello-world-sql-webapp-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-messaging-pubsub/0.7.0-M2-incubating/brooklyn-example-simple-messaging-pubsub-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-parent/0.7.0-M2-incubating/brooklyn-examples-parent-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-webapp/0.7.0-M2-incubating/brooklyn-example-hello-world-webapp-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-nosql-cluster/0.7.0-M2-incubating/brooklyn-example-simple-nosql-cluster-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+      <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-webapps-parent/0.7.0-M2-incubating/brooklyn-examples-webapps-parent-0.7.0-M2-incubating.jar</entry> <!--  BROOKLYN_VERSION  -->
+    </classpath>
+
+
+</catalog>

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/build/eclipse.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/eclipse.include.md b/docs/guide/dev/build/eclipse.include.md
new file mode 100644
index 0000000..e0dc3c0
--- /dev/null
+++ b/docs/guide/dev/build/eclipse.include.md
@@ -0,0 +1,15 @@
+
+- Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases), or for kepler [http://download.eclipse.org/releases/kepler](http://download.eclipse.org/releases/kepler)
+  (typically bundled with Eclipse or available in the default update site set)
+
+- Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates)
+  (typically bundled with Eclipse or available in the default update site set)
+
+- Groovy Plugin: GRECLIPSE from 
+  [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3) 
+  (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2) 
+  or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)).
+  Be sure to include Groovy 1.8.6 compiler support and Maven-Eclipse (m2e) support. 
+  More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin).
+
+- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse)

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/build/ide.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/ide.md b/docs/guide/dev/build/ide.md
new file mode 100644
index 0000000..3abae3c
--- /dev/null
+++ b/docs/guide/dev/build/ide.md
@@ -0,0 +1,123 @@
+---
+layout: guide-normal
+title: IDE Setup
+toc: /guide/toc.json
+---
+
+Gone are the days when IDE integration always just works...  Maven and Eclipse fight, 
+neither quite gets along perfectly with Groovy,
+git branch switches (sooo nice) can be slow, etc etc.
+
+But with a bit of a dance the IDE can still be your friend,
+making it much easier to run tests and debug.
+
+As a general tip, don't always trust the IDE to build correctly; if you hit a snag,
+do a command-line ``mvn clean install`` (optionally with ``-DskipTests``)
+then refresh the project. 
+
+See instructions below for specific IDEs.
+
+
+## Eclipse
+
+If you're an Eclipse user, you'll probably want the Maven (m2e) plugin
+and the Groovy Eclipse plugin (used for testing and examples primarily).
+You may also want Git and TestNG plugins.
+You can install these using Help -> Install New Software, or from the Eclipse Marketplace:
+
+{% readj eclipse.include.md %}
+
+As of this writing, Eclipse 4.2 and Eclipse 4.3 are commonly used, 
+and the codebase can be imported (Import -> Existing Maven Projects) 
+and successfully built and run inside an IDE.
+However there are quirks, and mileage may vary.
+
+If you encounter issues, the following hints may be helpful:
+
+* If you attempt to import projects before the plugins are installed, you may encounter errors such as 
+  '``No marketplace entries found to handle maven-compiler-plugin:2.3.2:compile in Eclipse``',
+  and the projects will not be recognized as java projects. If you do, simply cancel the import 
+  (or delete the imported projects if they have been imported) and install the plugins as described above.
+  If you have installed plugins from alternative locations, remove them and re-install them from the locations
+  specified above.
+
+* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh
+  can be useful to re-populate files which need to be copied to `target/`
+ 
+* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files
+  (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install
+  from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix 
+  `.classpath`s).
+  Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure)
+  or the filesystem, or use
+  the following command to remove these rogue blocks in the generated `.classpath` files:
+
+{% highlight bash %}
+% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \;
+{% endhighlight %}
+
+* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later".
+  The build-helper connector is useful if you're prompted for it, but
+  do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway).
+  You can manually mark as permanently ignored certain errors;
+  this updates the pom.xml (and should be current).
+
+* You may need to ensure ``src/main/{java,resources}`` is created in each project dir,
+  if (older versions) complain about missing directories,
+  and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists):
+
+{% highlight bash %}
+find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \;
+{% endhighlight %}
+
+* You may need to add the groovy nature (or even java nature) to projects;
+  with some maven-eclipse plugins this works fine, 
+  but for others (older ones) you may need to handcraft these 
+  (either right-click the project in the Package Explorer and choose Configure,
+  or edit the ``.project`` manually adding it to the project properties).
+  The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful. 
+
+If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.path.guide}}/meta/contact.html) and we can hopefully share our pearls.
+(And if you have a tip we haven't mentioned please let us know that too!)
+
+
+
+## IntelliJ IDEA
+
+To develop or debug Brooklyn in IntelliJ, you will need to ensure that the Groovy and TestNG plugins are installed
+via the IntelliJ IDEA | Preferences | Plugins menu. Once installed, you can open Brooklyn from the root folder, 
+(e.g. ``~/myfiles/brooklyn``) which will automatically open the subprojects.
+
+There have previously been issues where the java 6 compiler incorrectly identified the return type of functions that use
+generics. These issues have been refactored away, however may return in future. If so, you can either set the java compiler
+level to 1.7, or setup IntelliJ to use the Eclipse compiler as per the instructions provided by JetBeans:
+
+> The problem seems to be caused by bug in java compiler from JDK 1.6, it is known to sometimes produce compilation 
+> errors for complicated code involving generic types. Java compiler from JDK 1.7 compiles your code successfully so I would 
+> recommend you to consider upgrading to JDK 1.7. If it isn't possible you can switch to Eclipse Compiler (Settings | 
+> Compiler | Java Compiler | "Use Compiler" combobox).
+
+
+## Netbeans
+
+Tips from Netbeans users wanted!
+
+
+
+## Debugging Tips
+
+To debug Brooklyn, create a launch configuration which launches the ``BrooklynJavascriptGuiLauncher`` class. NOTE: You may
+need to add additional projects or folders to the classpath of the run configuration (e.g. add the brooklyn-software-nosql
+project if you wish to deploy a MongoDBServer). You will also need to ensure that the working directory is set to the jsgui
+folder. For IntelliJ, you can set the 'Working directory' of the Run/Debug Configuration to ``$MODULE_DIR/../jsgui``. For
+Eclipse, use the default option of ``${workspace_loc:brooklyn-jsgui}``.
+
+To debug the jsgui (the Brooklyn web console), you will need to build Brooklyn with -DskipOptimization to prevent the build from minifying the javascript.
+When building via the command line, use the command ``mvn clean install -DskipOptimization``, and if you are using IntelliJ IDEA, you can add the option
+to the Maven Runner by clicking on the Maven Settings icon in the Maven Projects tool window  and adding the ``skipOptimization`` property with no value.
+
+When running at the command line you can enable remote connections so that one can attach a debugger to the Java process:
+    Run Java with the following on the command line or in JAVA_OPTS: ``-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005``
+
+To debug a brooklyn instance that has been run with the above JAVA_OPTS, create a remote build configuration (IntelliJ - 
+Run | Edit Configurations | + | Remote) with the default options, ensuring the port matches the address specified in JAVA_OPTS.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/build/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/index.md b/docs/guide/dev/build/index.md
new file mode 100644
index 0000000..90aa6fa
--- /dev/null
+++ b/docs/guide/dev/build/index.md
@@ -0,0 +1,184 @@
+---
+layout: guide-normal
+title: Maven Build
+toc: /guide/toc.json
+---
+
+## The Basics
+
+To build the code, you need Maven (v3) installed and Java (1.6).
+With that in place, you should be able to build everything with a:
+
+{% highlight bash %}
+brooklyn% mvn clean install
+{% endhighlight %}
+
+Key things to note if you're new to Maven:
+
+* You may need more JVM memory, e.g. at the command-line (or in `.profile`):
+
+  ``export MAVEN_OPTS="-Xmx1024m -Xms512m -XX:MaxPermSize=256m``
+
+* You can do this in specific projects as well.
+
+* Add ``-DskipTests`` to skip tests. 
+
+* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests
+  ([tests described here](tests.html))
+
+* Nearly all the gory details are in the root ``pom.xml``, which is referenced by child project poms.
+
+* You can also open and use the code in your favourite IDE,
+  although you may hit a few **[snags](ide.html)**
+  (that link has some tips for resolving them too)
+
+
+## When the RAT Bites
+
+We use RAT to ensure that all files are compliant to Apache standards.  Most of the time you shouldn't see it or need to know about it, but if it detects a violation, you'll get a message such as:
+
+    [ERROR] Failed to execute goal org.apache.rat:apache-rat-plugin:0.10:check (default) on project brooklyn-parent: Too many files with unapproved license: 1 See RAT report in: /Users/alex/Data/cloudsoft/dev/gits/brooklyn/target/rat.txt -> [Help 1]
+
+If there's a problem, see the file `rat.txt` in the `target` directory of the failed project.  (Maven will show you this link in its output.)
+
+Often the problem is one of the following:
+
+* You've added a file which requires the license header but doesn't have it
+
+  **Resolution:**  Simply copy the header from another file
+
+* You've got some temporary files which RAT things should have headers
+
+  **Resolution:**  Move the files away, add headers, or turn off RAT (see below)
+
+* The project structure has changed and you have stale files (e.g. in a `target` directory)
+
+  **Resolution:**  Remove the stale files, e.g. with `git clean -df` (and if needed a `find . -name target -prune -exec rm -rf {} \;` to delete folders named `target`)
+
+To disable RAT checking on a build, set `rat.ignoreErrors`, e.g. `mvn -Drat.ignoreErrors=true clean install`.  (But note you will need RAT to pass in order for a PR to be accepted!)
+
+If there is a good reason that a file, pattern, or directory should be permanently ignored, that is easy to add inside the root `pom.xml`.
+
+
+## Other Handy Hints
+
+* On some **Ubuntu** (e.g. 10.4 LTS) maven v3 is not currently available from the repositories.
+  Some instructions for installing at are [at superuser.com](http://superuser.com/questions/298062/how-do-i-install-maven-3).
+
+* The **mvnf** script 
+  ([get the gist here](https://gist.github.com/2241800)) 
+  simplifies building selected projects, so if you just change something in ``software-webapp`` 
+  and then want to re-run the examples you can do:
+  
+  ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}`` 
+
+* The **developers catalog** ([developers-catalog.xml](developers-catalog.xml)) uses artifacts from your local `~/.m2/repository/...` (after building from source). This avoids unnecessary web requests to Maven Central or Sonatype, and will allow you to work off-line.
+  
+  ``wget {{site.url_root}}{{site.path.guide}}/dev/build/developers-catalog.xml > ~/.brooklyn/catalog.xml`` 
+
+## Appendix: Sample Output
+
+A healthy build will look something like the following,
+including a few warnings (which we have looked into and
+understand to be benign and hard to get rid of them,
+although we'd love to if anyone can help!):
+
+{% highlight bash %}
+brooklyn% mvn clean install
+[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Build Order:
+[INFO] 
+[INFO] Brooklyn Parent Project
+[INFO] Brooklyn Utilities to Support Testing (listeners etc)
+[INFO] Brooklyn Logback Includable Configuration
+[INFO] Brooklyn Common Utilities
+[INFO] Brooklyn Groovy Utilities
+[INFO] Brooklyn API
+
+...
+
+[WARNING] Ignoring project type war - supportedProjectTypes = [jar]
+
+...
+
+[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in /Users/aled/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar
+
+...
+
+[INFO] — maven-assembly-plugin:2.3:single (build-distribution-dir) @ brooklyn-dist —
+[INFO] Reading assembly descriptor: src/main/config/build-distribution-dir.xml
+[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
+[INFO] Copying files to /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist
+[WARNING] Assembly file: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment.
+
+...
+
+[INFO] — maven-assembly-plugin:2.3:single (build-distribution-archive) @ brooklyn-dist —
+[INFO] Reading assembly descriptor: src/main/config/build-distribution-archive.xml
+[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
+[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-SNAPSHOT-dist.tar.gz
+[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
+
+...
+
+[WARNING] Don't override file /Users/aled/repos/apache/incubator-brooklyn/usage/archetypes/quickstart/target/test-classes/projects/integration-test-1/project/brooklyn-sample/src/main/resources/sample-icon.png
+
+...
+
+[INFO] Reactor Summary:
+[INFO] 
+[INFO] Brooklyn Parent Project ........................... SUCCESS [3.072s]
+[INFO] Brooklyn Utilities to Support Testing (listeners etc)  SUCCESS [3.114s]
+[INFO] Brooklyn Logback Includable Configuration ......... SUCCESS [0.680s]
+[INFO] Brooklyn Common Utilities ......................... SUCCESS [7.263s]
+[INFO] Brooklyn Groovy Utilities ......................... SUCCESS [5.193s]
+[INFO] Brooklyn API ...................................... SUCCESS [2.146s]
+[INFO] Brooklyn Test Support ............................. SUCCESS [2.517s]
+[INFO] CAMP Server Parent Project ........................ SUCCESS [0.075s]
+[INFO] CAMP Base ......................................... SUCCESS [4.079s]
+[INFO] Brooklyn REST Swagger Apidoc Utilities ............ SUCCESS [1.983s]
+[INFO] Brooklyn Logback Configuration .................... SUCCESS [0.625s]
+[INFO] CAMP Server ....................................... SUCCESS [5.446s]
+[INFO] Brooklyn Core ..................................... SUCCESS [1:24.122s]
+[INFO] Brooklyn Policies ................................. SUCCESS [44.425s]
+[INFO] Brooklyn Hazelcast Storage ........................ SUCCESS [7.143s]
+[INFO] Brooklyn Jclouds Location Targets ................. SUCCESS [16.488s]
+[INFO] Brooklyn Secure JMXMP Agent ....................... SUCCESS [8.634s]
+[INFO] Brooklyn JMX RMI Agent ............................ SUCCESS [2.315s]
+[INFO] Brooklyn Software Base ............................ SUCCESS [28.538s]
+[INFO] Brooklyn Network Software Entities ................ SUCCESS [3.896s]
+[INFO] Brooklyn OSGi Software Entities ................... SUCCESS [4.589s]
+[INFO] Brooklyn Web App Software Entities ................ SUCCESS [17.484s]
+[INFO] Brooklyn Messaging Software Entities .............. SUCCESS [7.106s]
+[INFO] Brooklyn Database Software Entities ............... SUCCESS [5.229s]
+[INFO] Brooklyn NoSQL Data Store Software Entities ....... SUCCESS [11.901s]
+[INFO] Brooklyn Monitoring Software Entities ............. SUCCESS [4.027s]
+[INFO] Brooklyn CAMP REST API ............................ SUCCESS [15.285s]
+[INFO] Brooklyn REST API ................................. SUCCESS [4.489s]
+[INFO] Brooklyn REST Server .............................. SUCCESS [30.270s]
+[INFO] Brooklyn REST Client .............................. SUCCESS [7.007s]
+[INFO] Brooklyn REST JavaScript Web GUI .................. SUCCESS [24.397s]
+[INFO] Brooklyn Launcher ................................. SUCCESS [15.923s]
+[INFO] Brooklyn Command Line Interface ................... SUCCESS [9.279s]
+[INFO] Brooklyn All Things ............................... SUCCESS [13.875s]
+[INFO] Brooklyn Distribution ............................. SUCCESS [49.370s]
+[INFO] Brooklyn Quick-Start Project Archetype ............ SUCCESS [12.053s]
+[INFO] Brooklyn Examples Aggregator Project .............. SUCCESS [0.085s]
+[INFO] Brooklyn Examples Support Aggregator Project - Webapps  SUCCESS [0.053s]
+[INFO] hello-world-webapp Maven Webapp ................... SUCCESS [0.751s]
+[INFO] hello-world-sql-webapp Maven Webapp ............... SUCCESS [0.623s]
+[INFO] Brooklyn Simple Web Cluster Example ............... SUCCESS [5.398s]
+[INFO] Brooklyn Global Web Fabric Example ................ SUCCESS [3.176s]
+[INFO] Brooklyn Simple Messaging Publish-Subscribe Example  SUCCESS [3.217s]
+[INFO] Brooklyn NoSQL Cluster Examples ................... SUCCESS [6.790s]
+[INFO] Brooklyn QA ....................................... SUCCESS [7.117s]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 8:33.983s
+[INFO] Finished at: Mon Jul 21 14:56:46 BST 2014
+[INFO] Final Memory: 66M/554M
+[INFO] ------------------------------------------------------------------------
+
+{% endhighlight %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/build/tests.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/tests.md b/docs/guide/dev/build/tests.md
new file mode 100644
index 0000000..f202dc2
--- /dev/null
+++ b/docs/guide/dev/build/tests.md
@@ -0,0 +1,26 @@
+---
+layout: guide-normal
+title: Tests
+toc: /guide/toc.json
+---
+
+We have the following tests groups:
+
+*     normal (i.e. no group) -- should run quickly, not need internet, and not side effect the machine (apart from a few /tmp files)          
+*     Integration -- deploys locally, may read and write from internet, takes longer.
+          If you change an entity, rerun the relevant integration test to make sure all is well!
+*     Live -- deploys remotely, may provision machines (but should clean up, getting rid of them in a try block)
+*     Live-sanity -- a sub-set of "Live" that can be run regularly; a trade-off of optimal code coverage for the 
+      time/cost of those tests.
+*     WIP -- short for "work in progress", this will disable the test from being run by the normal brooklyn maven profiles,
+      while leaving the test enabled so that one can work on it in IDEs or run the selected test(s) from the command line.
+*     Acceptance -- this (currently little-used) group is for very long running tests, such as soak tests
+
+To run these from the command line, use something like the following:
+
+*     normal: `mvn clean install`
+*     integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true`
+*     Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true`
+*     Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true`
+
+<!-- TODO describe how to run each of these, as a group, and individually; and profiles -->

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/build/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/toc.json b/docs/guide/dev/build/toc.json
new file mode 100644
index 0000000..192f1e3
--- /dev/null
+++ b/docs/guide/dev/build/toc.json
@@ -0,0 +1,8 @@
+[
+{ "title": "Maven",
+  "file":  "{{ site.path.guide }}/dev/build/index.html" },
+{ "title": "IDE",
+  "file": "{{ site.path.guide }}/dev/build/ide.html" },
+{ "title": "Tests",
+  "file":  "{{ site.path.guide }}/dev/build/tests.html" }
+]

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/code/entity.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/entity.md b/docs/guide/dev/code/entity.md
new file mode 100644
index 0000000..f84e23c
--- /dev/null
+++ b/docs/guide/dev/code/entity.md
@@ -0,0 +1,91 @@
+---
+layout: guide-normal
+title: Writing an Entity
+toc: /guide/toc.json
+---
+
+## Ways to write an entity
+
+There are several ways to write a new entity:
+
+* Write pure-java, extending existing base-classes and using utilities such as `HttpTool` and `BashCommands`.
+* Write scripts, and configure (e.g. using YAML) a **`VanillaSoftwareProcess`**.
+* Use Chef recipes, and wire these into the entity by using `ChefConfig` and `ChefLifecycleEffectorTasks`.
+* Use an equivalent of Chef (e.g. Salt or Puppet; support for these is currently less mature than for Chef)
+
+The rest of this section covers writing an entity in pure-java (or other JVM languages).
+
+
+## Things To Know
+
+All entities have an interface and an implementation. The methods on the interface 
+are its effectors; the interface also defines its sensors.
+
+Entities are created through the management context (rather than calling the  
+constructor directly). This returns a proxy for the entity rather than the real 
+instance, which is important in a distributed management plane.
+
+All entity implementations inherit from `AbstractEntity`, 
+often through one of the following:
+
+* **`SoftwareProcessImpl`**:  if it's a software process
+* **`VanillaJavaAppImpl`**:  if it's a plain-old-java app
+* **`JavaWebAppSoftwareProcessImpl`**:  if it's a JVM-based web-app
+* **`DynamicClusterImpl`**, **`DynamicGroupImpl`** or **`AbstractGroupImpl`**:  if it's a collection of other entities
+
+Software-based processes tend to use *drivers* to install and
+launch the remote processes onto *locations* which support that driver type.
+For example, `AbstractSoftwareProcessSshDriver` is a common driver superclass,
+targetting `SshMachineLocation` (a machine to which Brooklyn can ssh).
+The various `SoftwareProcess` entities above (and some of the exemplars 
+listed at the end of this page) have their own dedicated drivers.
+
+Finally, there are a collection of *traits*, such as `Resizable`, 
+in the package ``brooklyn.entity.trait``. These provide common
+sensors and effectors on entities, supplied as interfaces.
+Choose one (or more) as appropriate.
+
+
+
+## Key Steps
+
+So to get started:
+
+1. Create your entity interface, extending the appropriate selection from above,
+   to define the effectors and sensors.
+2. Include an annotation like `@ImplementedBy(YourEntityImpl.class)` on your interface,
+   where `YourEntityImpl` will be the class name for your entity implementation.
+3. Create your entity class, implementing your entity interface and extending the 
+   classes for your chosen entity super-types. Naming convention is a suffix "Impl"
+   for the entity class, but this is not essential.
+4. Create a driver interface, again extending as appropriate (e.g. `SoftwareProcessDriver`).
+   The naming convention is to have a suffix "Driver". 
+5. Create the driver class, implementing your driver interface, and again extending as appropriate.
+   Naming convention is to have a suffix "SshDriver" for an ssh-based implementation.
+   The correct driver implementation is found using this naming convention, or via custom
+   namings provided by the `BasicEntityDriverFactory`.
+6. Wire the `public Class getDriverInterface()` method in the entity implementation, to specify
+   your driver interface.
+7. Provide the implementation of missing lifecycle methods in your driver class (details below)
+8. Connect the sensors from your entity (e.g. overriding `connectSensors()` of `SoftwareProcessImpl`)..
+   See the sensor feeds, such as `HttpFeed` and `JmxFeed`.
+
+Any JVM language can be used to write an entity. However use of pure Java is encouraged for
+entities in core brooklyn. 
+
+
+## Helpful References
+
+A few handy pointers will help make it easy to build your own entities.
+Check out some of the exemplar existing entities
+(note, some of the other entities use deprecated utilities and a deprecated class 
+hierarchy; it is suggested to avoid these, looking at the ones below instead):
+
+* `JBoss7Server`
+* `MySqlNode`
+
+You might also find the following helpful:
+
+* **[Entity Design Tips]({{site.path.guide}}/dev/tips/index.html#EntityDesign)**
+* The **[User Guide]({{site.path.guide}}/use/guide/index.html)**
+* The **[Mailing List](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)**

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/code/index.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/index.include.md b/docs/guide/dev/code/index.include.md
new file mode 100644
index 0000000..d25c163
--- /dev/null
+++ b/docs/guide/dev/code/index.include.md
@@ -0,0 +1,96 @@
+## The Basics
+
+Brooklyn is available at [GitHub apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn).  Check it out using:
+
+{% highlight bash %}
+git clone git@github.com:apache/incubator-brooklyn.git
+cd brooklyn
+{% endhighlight %}
+
+Build it with:
+
+{% highlight bash %}
+mvn clean install
+{% endhighlight %}
+
+And launch it with:
+
+{% highlight bash %}
+cd usage/dist/target/brooklyn-dist/
+bin/brooklyn launch
+{% endhighlight %}
+
+Plenty of examples are in the **examples** sub-dir,
+described [here]({{site.path.guide}}/use/examples).
+
+Information on using Brooklyn -- configuring locations (in `brooklyn.properties`) 
+and adding new projects to a catalog -- can be found in the [User's Guide]({{site.path.guide}}/use/guide/quickstart/index.html).
+This document is intended to help people become familiar with the codebase.
+
+## Project Structure
+
+Brooklyn is split into the following projects and sub-projects:
+
+* **``camp``**: the components for a server which speaks the CAMP REST API and which understands the CAMP YAML plan language
+* **``api``**: the pure-Java interfaces for interacting with the system
+* **``core``**: the base class implementations for entities and applications, entity traits, locations, policies, sensor and effector support, tasks, and more 
+* **``locations``**: specific location integrations
+    * **``jclouds``**: integration with many cloud APIs and providers, via Apache jclouds
+* **``policies``**: collection of useful policies for automating entity activity  
+* **``software``**: entities which are mainly launched by launched software processes on machines, and collections thereof
+    * **``base``**: software process lifecycle abstract classes and drivers (e.g. SSH) 
+    * **``webapp``**: web servers (JBoss, Tomcat), load-balancers (Nginx), and DNS (Geoscaling) 
+    * **``database``**: relational databases (SQL) 
+    * **``nosql``**: datastores other than RDBMS/SQL (often better in distributed environments) 
+    * **``messaging``**: messaging systems, including Qpid, Apache MQ, RabbitMQ 
+    * **``monitoring``**: monitoring tools, including Monit
+    * **``osgi``**: OSGi servers 
+    * **...**
+* **``utils``**: projects which lower level utilities
+    * **common**: Utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+    * **groovy**: Groovy extensions and utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+    * **jmx/jmxmp-ssl-agent**: An agent implementation that can be attached to a Java process, to give expose secure JMXMP
+    * **jmx/jmxrmi-agent**: An agent implementation that can be attached to a Java process, to give expose JMX-RMI without requiring all high-number ports to be open
+    * **rest-swagger**: Swagger REST API utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+    * **test-support**: Test utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+* **``usage``**: projects which make Brooklyn easier to use, either for end-users or Brooklyn developers
+    * **all**: maven project to supply a shaded JAR (containing all dependencies) for convenience
+    * **archetypes**: A maven archetype, for easily generating the structure of a new downstream projects 
+    * **camp**: Brooklyn bindings for the CAMP REST API
+    * **cli**: backing implementation for Brooklyn's command line interface
+    * **dist**: builds brooklyn as a downloadable .zip and .tar.gz
+    * **jsgui**: Javascript web-app for the brooklyn management web console (builds a WAR)
+    * **launcher**: for launching brooklyn, either using a main method or invoked from the cli project
+    * **logback-includes**: Various helpful logback XML files that can be included; does not contain logback.xml 
+    * **logback-xml**: Contains a logback.xml that references the include files in brooklyn-logback-includes
+    * **rest-api**: The API classes for the Brooklyn REST api
+    * **rest-client**: A client Java implementation for using the Brooklyn REST API 
+    * **rest-server**: The server-side implementation of the Brooklyn REST API
+    * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts)
+    * **qa**: longevity and stress tests
+    * **test-support**: provides Brooklyn-specific support for tests, used by nearly all projects in scope ``test``
+* **``docs``**: the markdown source code for this documentation, as described [here]({{site.path.guide}}/dev/tips/update-docs.html)
+* **``examples``**: some canonical examples, as listed [here]({{site.path.guide}}/use/examples)
+* **``sandbox``**: various projects, entities, and policies which the Brooklyn Project is incubating
+
+ 
+## Next Steps
+
+If you're interested in building and editing the code, check out:
+
+* [Maven setup](../build/index.html)
+* [IDE setup](../build/ide.html)
+* [Tests](../build/tests.html)
+* [Tips](../tips/index.html)
+
+If you want to start writing your own policies and entities, have a look at:
+
+* [Writing a Brooklyn Entity](entity.html)
+* [Writing a Brooklyn Policy](policy.html)
+* Or see the [User Guide]({{ site.path.guide }}/use/guide/index.html) 
+  on [policies]({{ site.path.guide }}/use/guide/policies/index.html)
+  and [entities]({{ site.path.guide }}/use/guide/entities/index.html)
+
+Where things aren't documented **please ask us** at 
+[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)
+so we can remedy this!

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/code/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/index.md b/docs/guide/dev/code/index.md
new file mode 100644
index 0000000..8220a8d
--- /dev/null
+++ b/docs/guide/dev/code/index.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Code Structure
+toc: /guide/toc.json
+---
+
+{% readj index.include.md %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/code/policy.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/policy.md b/docs/guide/dev/code/policy.md
new file mode 100644
index 0000000..a62bdd2
--- /dev/null
+++ b/docs/guide/dev/code/policy.md
@@ -0,0 +1,47 @@
+---
+layout: guide-normal
+title: Writing a Policy
+toc: /guide/toc.json
+---
+
+Policies perform the active management enabled by Brooklyn.  
+Each policy instance is associated with an entity,
+and at runtime it will typically subscribe to sensors on that entity or children,
+performing some computation and optionally actions when a subscribed sensor event occurs.
+This action might be invoking an effector or emitting a new sensor,
+depending the desired behvaiour is.
+
+Writing a policy is straightforward.
+Simply extend ``AbstractPolicy``,
+overriding the ``setEntity`` method to supply any subscriptions desired:
+
+{% highlight java %}
+    @Override
+    public void setEntity(EntityLocal entity) {
+        super.setEntity(entity)
+        subscribe(entity, TARGET_SENSOR, this)
+    }
+{% endhighlight %}
+
+and supply the computation and/or activity desired whenever that event occurs:
+
+{% highlight java %}
+    @Override
+    public void onEvent(SensorEvent<Integer> event) {
+        int val = event.getValue()
+        if (val % 2 == 1)
+            entity.sayYoureOdd();
+    }
+{% endhighlight %}
+
+You'll want to do more complicated things, no doubt,
+like access other entities, perform multiple subscriptions,
+and emit other sensors -- and you can.
+See the source code, and see some commonly used policies
+in ``AutoScalerPolicy`` and ``RollingMeanEnricher``. 
+
+One rule of thumb, to close on:
+try to keep policies simple, and compose them together at runtime;
+for instance, if a complex computation triggers an action,
+define one **enricher** policy to aggregate other sensors and emit a new sensor,
+then write a second policy to perform that action.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/code/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/toc.json b/docs/guide/dev/code/toc.json
new file mode 100644
index 0000000..6bb112b
--- /dev/null
+++ b/docs/guide/dev/code/toc.json
@@ -0,0 +1,10 @@
+[
+{ "title": "Structure",
+  "file":  "{{ site.path.guide }}/dev/code/index.html" },
+{ "title": "Writing an Entity",
+  "file": "{{ site.path.guide }}/dev/code/entity.html" },
+{ "title": "Writing a Policy",
+  "file":  "{{ site.path.guide }}/dev/code/policy.html" },
+{ "title": "brooklyn.git (github)",
+  "file":  "http://github.com/apache/incubator-brooklyn" }
+]

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/how-to-contrib.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/how-to-contrib.md b/docs/guide/dev/how-to-contrib.md
new file mode 100644
index 0000000..120d3d9
--- /dev/null
+++ b/docs/guide/dev/how-to-contrib.md
@@ -0,0 +1,38 @@
+---
+layout: guide-normal
+title: How to Contribute
+toc: /guide/toc.json
+---
+
+### The Process
+
+If you've built something which you think others could use, or are interested in doing so -- 
+whether a new supported entity, or a policy, or an example --
+it's easy to give back to the community.  Just:
+
+1. **Tell [the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)** about your work or interest
+
+1. **Create your fork** of the project on GitHub
+
+1. **Clone it** to your local machine and do your work on it
+
+1. **Push it**, and tell everyone about it
+
+1. **Sign the relevant Apache contributor agreement(s)**
+
+1. **Issue a pull request** from your GitHub repo
+
+The same process holds for contributing to this documentation (web site and user guide),
+but see the additional [tips for updating documentation]({{ site.path.guide }}/dev/tips/update-docs.html).
+
+
+### Some Words of Advice
+
+* Do early-stage work in the ``/sandbox``, which means we can pulled it in to ``master`` more often --
+  keeping branches short-lived and making it easier to collaborate!
+               
+* Include javadoc and tests
+
+* See the [tips here]({{site.path.guide}}/dev/tips/index.html)
+
+* If you get blocked, **[hollar]({{site.path.guide}}/meta/contact.html)**!

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/index.md b/docs/guide/dev/index.md
new file mode 100644
index 0000000..c6c9e33
--- /dev/null
+++ b/docs/guide/dev/index.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Getting to Code
+toc: /guide/toc.json
+---
+
+{% readj code/index.include.md %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/links.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/links.md b/docs/guide/dev/links.md
new file mode 100644
index 0000000..6fd12e2
--- /dev/null
+++ b/docs/guide/dev/links.md
@@ -0,0 +1,22 @@
+---
+layout: guide-normal
+title: Development Bookmarks
+toc: ../toc.json
+---
+
+{% include fields.md %}
+
+Handy places:
+
+* **Code** is in Github at [https://github.com/apache/incubator-brooklyn/](https://github.com/apache/incubator-brooklyn/)
+
+* **Issues** are in Jira at [https://issues.apache.org/jira/browse/BROOKLYN/](https://issues.apache.org/jira/browse/BROOKLYN/)
+
+* **Maven repositories** are:
+  * [Apache releases]({{ apache_releases_repo_groupid_url }})
+  * [Apache snapshots]({{ apache_snapshots_repo_groupid_url }})
+  * Other repositories are at [http://developers.cloudsoftcorp.com/download/maven2/](http://developers.cloudsoftcorp.com/download/maven2/) for releases 
+  and [http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/](http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/) for snapshots
+            
+* **CI server** is a jenkins server at: [https://builds.apache.org/job/incubator-brooklyn-master-build/](https://builds.apache.org/job/incubator-brooklyn-master-build/)
+

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/tips/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/index.md b/docs/guide/dev/tips/index.md
new file mode 100644
index 0000000..e809b7d
--- /dev/null
+++ b/docs/guide/dev/tips/index.md
@@ -0,0 +1,50 @@
+---
+layout: guide-normal
+title: Miscellaneous Tips and Tricks
+toc: /guide/toc.json
+---
+
+## General Good Ways of Working
+
+* If working on something which could be contributed to Brooklyn,
+  do it in a project under the ``sandbox`` directory.
+  This means we can accept pulls more easily (as sandbox items aren't built as part of the main build)
+  and speed up collaboration.
+  
+* When debugging an entity, make sure the  [brooklyn.SSH logger](logging.html) is set to DEBUG and accessible.
+ 
+* Use tests heavily!  These are pretty good to run in the IDE (once you've completed [IDE setup]({{site.path.guide}}/dev/build/ide.html)),
+  and far quicker to spot problems than runtime, plus we get early-warning of problems introduced in the future.
+  (In particular, Groovy's laxity with compilation means it is easy to introduce silly errors which good test coverage will find much faster.)
+  
+* If you hit inexplicable problems at runtime, try clearing your Maven caches,
+  or the brooklyn-relevant parts, under ``~/.m2/repository``.
+  Also note your IDE might be recompiling at the same time as a Maven command-line build,
+  so consider turning off auto-build.
+
+
+<a name="EntityDesign"></a>
+## Entity Design Tips
+
+* Look at related entities and understand what they've done, in particular which
+  sensors and config keys can be re-used.
+  (Many are inherited from interfaces, where they are declared as constants,
+  e.g. ``Attributes`` and ``UsesJmx``.)
+  
+* Understand the location hierarchy:  software process entities typically get an ``SshMachineLocation``,
+  and use a ``*SshDriver`` to do what they need.  This will usually have a ``MachineProvisioningLocation`` parent, e.g. a
+  ``JcloudsLocation`` (e.g. AWS eu-west-1 with credentials) or possibly a ``LocalhostMachineProvisioningLocation``.
+  Clusters will take such a ``MachineProvisioningLocation`` (or a singleton list); fabircs take a list of locations.
+  Some PaaS systems have their own location model, such as ``OpenShiftLocation``.
+
+Finally, don't be shy about [talking with others]({{site.path.guide}}/meta/contact.html), 
+that's far better than spinning your wheels (or worse, having a bad experience),
+plus it means we can hopefully improve things for other people!
+
+
+## Project Maintenance
+
+* Adding a new project may need updates to ``/pom.xml`` ``modules`` section and ``usage/all`` dependencies
+ 
+* Adding a new example project may need updates to ``/pom.xml`` and ``/examples/pom.xml`` (and the documentation too!)
+

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/tips/local-artifact-repo.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/local-artifact-repo.md b/docs/guide/dev/tips/local-artifact-repo.md
new file mode 100644
index 0000000..455a545
--- /dev/null
+++ b/docs/guide/dev/tips/local-artifact-repo.md
@@ -0,0 +1,32 @@
+---
+layout: guide-normal
+title: Prepopulating a Local Artifact Repository
+toc: /guide/toc.json
+---
+
+On occasion it can be useful to have/control/prepopulate a local repository of entity installers <small>[1]</small>.
+
+The following command (run from `~/`) may be used to sync Cloudsoft's fallback repository to the local `~/.brooklyn/repository/` folder:
+
+	wget --directory-prefix=".brooklyn/repository/" --no-parent --relative --no-host-directories --reject="index.html*" --cut-dirs=2 --recursive -e robots=off --user-agent="Brooklyn Repository Sync" http://downloads.cloudsoftcorp.com/brooklyn/repository/
+
+Brooklyn's default search behaviour for installation artifacts is as follows:
+
+1.  The local `~/.brooklyn/repository/` folder.
+2.	The entity's installer's public download url (or an overridden url if one has been specified).
+3.	Cloudsoft's fallback repository.
+
+Cloudsoft's fallback repository <small>[2]</small> contains many of the installation artifacts used by current Brooklyn entities. 
+
+It is intended to prevent problems occurring when the public url for an installer changes (e.g. when several new versions of MySQL have been released). It is provided on an as-is and as-available basis.
+
+If you use this command to create a local repository, please respect the `--user-agent`. In future this will allow Cloudsoft to easily filter repository syncing behaviour from  fallback behaviour, allowing out-of-date entities to be more easily identified and updated. 
+
+<br />
+<small>
+<ol>
+<li>For example, when establishing a local cache or enterprise golden source, or when developing Brooklyn while offline, in planes, trains and automobiles, or other such situations of exemplary derring-do <small>[3]</small>.</li> 
+<li><a href="http://downloads.cloudsoftcorp.com/brooklyn/repository/">downloads.cloudsoftcorp.com/brooklyn/repository</a></li>
+<li>This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.</li>
+</ol>
+</small>

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/201818b0/docs/guide/dev/tips/logging.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/logging.md b/docs/guide/dev/tips/logging.md
new file mode 100644
index 0000000..e9e3ffc
--- /dev/null
+++ b/docs/guide/dev/tips/logging.md
@@ -0,0 +1,140 @@
+---
+layout: guide-normal
+title: Logging
+toc: /guide/toc.json
+---
+
+## Logging: A Quick Overview
+
+For logging, we use **logback** which implements the slf4j API.
+This means you can use any slf4j compliant logging framework,
+with a default configuration which just works out of the box
+and bindings to the other common libraries (``java.util.logging``, ``log4j``, ...)
+if you prefer one of those.
+
+To use:
+
+* **Users**:
+If using a brooklyn binary installation, simply edit the ``logback.xml``
+or ``logback-custom.xml`` supplied in the archive, sometimes in a ``conf/``
+directory.
+
+* **Developers**:
+When setting up a new project, if you want logging it is recommended to include 
+the ``brooklyn-logback-xml`` project as an *optional* and *provided* maven dependency, 
+and then to put custom logging configuration in either ``logback-custom.xml`` or ``logback-main.xml``, 
+as described below.
+
+
+## Customizing Your Logging
+
+The project ``brooklyn-logback-xml`` supplies a ``logback.xml`` configuration,
+with a mechanism which allows it to be easily customized, consumed, and overridden.
+You may wish to include this as an *optional* dependency so that it is not forced
+upon downstream projects.  This ``logback.xml`` file supplied contains just one instruction,
+to include ``logback-main.xml``, and that file in turn includes:
+
+* ``logback-custom.xml``
+* ``brooklyn/logback-appender-file.xml``
+* ``brooklyn/logback-appender-stdout.xml``
+* ``brooklyn/logback-logger-excludes.xml``
+* ``brooklyn/logback-debug.xml``
+   
+For the most common customizations, simply create a ``logback-custom.xml`` on your classpath
+(ensuring it is loaded *before* brooklyn classes in classpath ordering in the pom)
+and supply your customizations there:  
+
+{% highlight xml %}
+<included>
+    <!-- filename to log to -->           
+    <property name="logging.basename" scope="context" value="acme-app" />
+    
+    <!-- additional loggers -->
+    <logger name="com.acme.app" level="DEBUG"/>
+</included>
+{% endhighlight %}
+
+For other configuration, you can override individual files listed above.
+For example:
+
+* To remove debug logging, create a trivial ``brooklyn/logback-debug.xml``, 
+  containing simply ``<included/>``.
+* To customise stdout logging, perhaps to give it a threshhold WARN instead of INFO,
+  create a ``brooklyn/logback-appender-stdout.xml`` which defines an appender STDOUT.
+* To discard all brooklyn's default logging, create a ``logback-main.xml`` which 
+  contains your configuration. This should look like a standard logback
+  configuration file, except it should be wrapped in ``<included>`` XML tags rather
+  than ``<configuration>`` XML tags (because it is included from the ``logback.xml``
+  which comes with ``brooklyn-logback-xml``.)
+
+You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``.
+If you do, logback will detect multiple files with that name and will scream at you.
+If you wish to supply your own ``logback.xml``, do **not** include ``brooklyn-logback-xml``.
+(Alternatively you can include a ``logback.groovy`` which causes logback to ignore ``logback.xml``.)
+
+You can set a specific logback config file to use with:
+
+{% highlight bash %}
+-Dlogback.configurationFile=/path/to/config.xml
+{% endhighlight %}
+
+
+## Assemblies
+
+When building an assembly, it is recommended to create a ``conf/logback.xml`` which 
+simply includes ``logback-main.xml`` (which comes from the classpath).  Users of the assembly
+can then edit the ``logback.xml`` file in the usual way, or they can plug in to the configuration 
+mechanisms described above, by creating files such as ``logback-custom.xml`` under ``conf/``.
+
+Including ``brooklyn-logback-xml`` as an *optional* and *provided* dependency means everything
+should work correctly in IDE's but it will not include the extra ``logback.xml`` file in the assembly.
+(Alternatively if you include the ``conf/`` dir in your IDE build, you should exclude this dependency.)
+
+With this mechanism, you can include ``logback-custom.xml`` and/or other files underneath 
+``src/main/resources/`` of a project, as described above (for instance to include custom
+logging categories and define the log file name) and it should get picked up, 
+both in the IDE and in the assembly.   
+ 
+
+## Tests
+
+Brooklyn projects ``test`` scope includes the ``brooklyn-utils-test-support`` project
+which supplies a ``logback-test.xml``. logback uses this file in preference to ``logback.xml``
+when available (ie when running tests). However the ``logback-test.xml`` Brooklyn uses
+includes the same ``logback-main.xml`` call path above, so your configurations should still work.
+
+The only differences of the ``logback-test.xml`` configuration is that:
+
+* Debug logging is included for all Brooklyn packages
+* The log file is called ``brooklyn-tests.log`` 
+
+
+## Caveats
+
+* logback uses SLF4J version 1.6 which is **not compatible** with 1.5.x. 
+  If you have dependent projects using 1.5.x (such as older Grails) things may break.
+
+* If you're not getting the logging you expect in the IDE, make sure 
+  ``src/main/resources`` is included in the classpath.
+  (In eclipse, right-click the project, the Build Path -> Configure,
+  then make sure all dirs are included (All) and excluded (None) -- 
+  ``mvn clean install`` should do this for you.)
+
+* You may find that your IDE logs to a file ``brooklyn-tests.log`` 
+  if it doesn't distinguish between test build classpaths and normal classpaths.
+
+* Logging configuration using file overrides such as this is very sensitive to
+  classpath order. To get a separate `brooklyn-tests.log` file during testing,
+  for example, the `brooklyn-test-support` project with scope `test` must be
+  declared as a dependency *before* `brooklyn-logback-includes`, due to the way
+  both files declare `logback-appender-file.xml`.
+  
+* Similarly note that the `logback-custom.xml` file is included *after* 
+  logging categories and levels are declared, but before appenders are declared,
+  so that logging levels declared in that file dominate, and that 
+  properties from that file apply to appenders.
+
+* Finally remember this is open to improvement. It's the best system we've found
+  so far but we welcome advice. In particular if it could be possible to include
+  files from the classpath with wildcards in alphabetical order, we'd be able
+  to remove some of the quirks listed above (though at a cost of some complexity!).


Mime
View raw message