Updated README with submodule maintenance instructions

diff --git a/README b/README
index d57aef26d8aa35567e313858ffbb0387adda2173..cc9af0f38b3d8272e92b99bb42e478535148b167 100644 (file)
--- a/README
+++ b/README
@@ -4,6 +4,7 @@ This is Mono.
        1. Installation
        2. Using Mono
        3. Directory Roadmap
+       4. git submodules maintenance
 
 1. Compilation and Installation
 ===============================
@@ -586,3 +587,68 @@ This is Mono.
                same prefix than this module gets.
 
 
+4. Git submodules maintenance
+=============================
+
+These instructions are for developers working on code in this repository. End users do not need to be
+concerned with the procedures described below. The description applies to each of the submodules used
+by mono. To list the submodules in use run:
+
+    git submodule
+
+If you have write access to the submodule repository do your work on it in a separate location, do not ever
+do any work in the mono copy of the submodule.
+
+All submodules should reside under the external/ directory off the top level Mono directory. If you want to add
+a new submodule, issue the following command from the Mono topmost directory:
+
+   git submodule add REPOSITORY_URL external/MODULE_NAME
+
+After that commit and push the changes to .gitmodule and the submodule itself.
+
+4.1 Submodule repository of origin maintenance
+==============================================
+
+The submodule repository of origin (at the REPOSITORY_URL above) must always be modified outside the Mono directory.
+The repository may be a fork or clone of yet another GIT repository, either on github or elsewhere. If this is the case,
+you must configure your clone of it by adding a remote reference to the upstream repository:
+
+    git remote add upstream UPSTREAM_URL
+
+When there exist upstream changes you need to merge, the following command needs to be used:
+
+    git fetch upstream/master
+
+followed by
+
+    git merge upstream/BRANCH_NAME
+
+and as soon as all the possible confilits are resolved, push the freshly integrated changes back to our repository
+
+    git push origin/BRANCH_NAME
+
+4.2 Submodule maintenance in Mono repository
+============================================
+
+When the submodule repository of origin is ready to be used by Mono, you need to go to the top level directory of
+Mono repository clone and make sure the submodules are checked out and up to date:
+
+    git submodule init
+    git submodule update --recursive
+
+Then in order to integrate changes from the submodule repository of origin:
+
+    cd external/MODULE_NAME
+    git pull
+
+you can, of course, use a a specific commit in the 'git pull' above instead of the default HEAD. When the changes are
+checked out, commit the changes to the Mono repository:
+
+    cd ../..
+    git add external/MODULE_NAME
+    git commit -m "Module MODULE_NAME updated"
+    git push
+
+It is _extremely_ important not to end the 'external/MODULE_NAME' reference above with a / since that will make git remove
+the submodule reference and commit all its contents as normal files to Mono directory. It is also required that you _always_
+push the submodule changes _before_ any and all work requiring the changes is done in the Mono repository.