diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..53fd51b
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,44 @@
+## Building this repo
+
+1. fetch sources
+
+    git clone http://git.eclipse.org/gitroot/webtools/webtools.releng.aggregator.git
+
+2. fetch submodules recursively, then update to latest on that branch
+
+    git submodule update --init --recursive
+    for d in webtools.*; do echo $d; pushd $d; git pull origin master; popd; done # **
+
+[NOTE]
+====
+If you fetch the main repo using a gerrit URL, such as `ssh://GITUSER@git.eclipse.org:29418/webtools/webtools.releng.aggregator.git` you may need to edit your `.git/config` file to replace the gerrit links with anonymous http ones, as not all the repos are set up for gerrit reviews yet.
+
+Lookin' at you, dali.
+====
+
+3. build
+
+    mvn clean install -V -B -Dmaven.test.skip=true -DskipWithIssues=false \
+      -Dmaven.test.error.ignore=true -Dmaven.test.failure.ignore=true \
+      -Dsurefire.timeout=1800 -P bree-libs -ff \
+      -Dplatform-repo.url=http://download.eclipse.org/eclipse/updates/4.8-I-builds/ \
+      -Dwebtools.buildSite=http://download.eclipse.org/webtools/downloads/drops/R3.10.0/I-3.10.0-20171004000115/ \
+      -Dtycho.version=1.0.0 -Dtycho-extras.version=1.0.0 -Pintegration \
+      | tee log.txt
+
+Note the above hacks:
+
+* platform-repo.url is a workaround for an invalid value in the parent pom
+* webtools.buildSite is a workaround for an invalid value in the parent pom, enabled because of -Pintegration
+* integration profile is needed to build the SDK features in webtools.servertools which are included in other features but have cross-repo dependencies
+* tycho versions are needed to ensure all the projects build with the same tycho version (instead of a mix of 0.22 and 1.0, which won't build
+
+---
+
+In future, this repo will likely be deprecated (or transform into something else) as webtools is moving away from a monolithic submodule-based uber-build and toward a sequential series of builds.
+
+This will allow users to build individual projects w/o having to check out the entire stack. For example, to contribute a fix to webtools.common, you need only fetch that project and build it by itself; then if you want to contribute a fix to a downstream project, such as webtools.servertools, you can rely on the latest local or CI build of webtools.common.
+
+This will allow development to be more agile, more reactive, and to move incrementally without the need for this project.
+
+-- 2017-10-13 @nickboldt