From b48cdd4f1a3235511b996c661bf72ebda8f9ff6e Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Sat, 28 Dec 2013 22:20:46 +0100
Subject: [PATCH] Add documentation for the new module system

---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 43 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 8434c078..3b5800d7 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,23 @@
 To build Gluon, after checkeing out the repository change to the source root directory
 to  perform the following commands:
 
-    git submodule update --init                                  # Get other repositories used by Gluon
     git clone git://github.com/freifunk-gluon/site-ffhl.git site # Get the Freifunk Lübeck site repository - or use your own!
+    make update                                                  # Get other repositories used by Gluon
     make                                                         # Build Gluon
 
-When calling make, the OpenWRT build environment is prepared/updated. To rebuilt
+When calling make, the OpenWRT build environment is prepared/updated. To rebuild
 the images only, just use:
 
     make images
 
-The built images can be found in the directory ./images.
+The built images can be found in the directory `images`.
 
 For the build reserve 6GB of disk space. The building requires packages
-for subversion, ncurses headers (libncurses-dev) and zlib headers
-(libz-dev).`
+for `subversion`, ncurses headers (`libncurses-dev`) and zlib headers
+(`libz-dev`).`
 
 
-There are three levels of 'make clean':
+There are three levels of `make clean`:
 
     make clean
 
@@ -25,8 +25,43 @@ will only clean the Gluon-specific files;
 
     make cleanall
 
-will also call 'make clean' on the OpenWRT tree, and
+will also call `make clean` on the OpenWRT tree, and
 
     make dirclean
 
-will do all this, and call 'make dirclean' on the OpenWRT tree.
+will do all this, and call `make dirclean` on the OpenWRT tree.
+
+
+# Development
+
+To update the repositories used by Gluon, just adjust the commit IDs in `modules` and
+rerun
+
+	make update
+
+The repository paths may be changed locally by creating a file `modules.local`.
+
+`make update` also applies the patches that can be found in the directories found in
+`patches`; the resulting branch will be called `patched`, while the commit specified in `modules`
+can be refered to by the branch `base`.
+
+    make unpatch
+
+sets the repositories to the `base` branch,
+
+     make patch
+
+re-applies the patches by resetting the `patched` branch to `base` and calling `git am`
+for the patch files. Calling `make` or a similar command after calling `make unpatch`
+is generally not a good idea.
+
+After new patches have been commited on top of the patched branch (or existing commits
+since the base commit have been edited or removed), the patch directories can be regenerated
+using
+	make update-patches
+
+If applying a patch fails because you have changed the base commit, the repository will be reset to the old `patched` branch
+and you can try rebasing it onto the new `base` branch yourself and after that call `make update-patches` to fix the problem.
+
+Always call `make update-patches` after making changes to a module repository as `make update` will overwrite your
+commits, making `git reflog` the only way to recover them!
\ No newline at end of file