From 9f954a0a1efde4fe44d9592ee29917ad3a6c81be Mon Sep 17 00:00:00 2001 From: Marek Habersack Date: Thu, 5 Apr 2012 20:53:42 +0200 Subject: [PATCH] Updated README with submodule maintenance instructions --- README | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/README b/README index d57aef26d8aa3..cc9af0f38b3d8 100644 --- 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.