[PATCH 2/2] add documentation about Git
nicolas.s-dev at laposte.net
Sun May 8 16:19:19 BST 2011
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev at laposte.net>
docs/FAQ.rst | 55 +++++++++++++++++
docs/HACKING.rst | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 222 insertions(+), 4 deletions(-)
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index fcc55b3..cd612ac 100644
@@ -355,6 +355,22 @@ accounts.
+I'm using git to install OfflineIMAP and found these branches called "master", "maint", "next", "pu" and "gh-pages". What are they?
+To be brief:
+* **gh-pages**: branch used to maintain the home page at github.
+* **master**: classical mainline branch.
+* **next**: this is the branch for recent merged patches. Used for testing OfflineIMAP.
+* **pu** ("proposed updates"): patches not ready for inclusion. This should **never** be checkouted!
+* **maint**: our long-living maintenance branch. We maintain this branch
+ (security and bugfixes) for users who don't want or can't upgrade to the
+ latest release.
+For more information about the branching model and workflow, see the HACKING page.
Why are your Maildir message filenames so long?
@@ -396,3 +412,42 @@ written in Korn, so you’ll need ksh, pdksh, or mksh to run it::
( exec /usr/bin/offlineimap -u Noninteractive.Quiet )
sleep 60 # prevents extended failure condition
+How to submit a patch?
+If you want to send regular patches, you should first subscribe to the `mailing
+list`_. This is not a pre-requisite, though.
+Next, you'll find documentation in the docs/ directory, especially the HACKING
+You'll need to get a clone from the official `OfflineIMAP`_ repository and
+configure Git. Then, read the SubmittingPatches.rst page in your local
+repository or at
+To send a patch, we recommend using 'git send-email'.
+Where from should my patches be based on?
+Depends. If you're not sure, it should start off of the master branch. master is
+the branch where new patches should be based on by default.
+Obvious materials for next release (e.g. new features) start off of current
+next. Also, next is the natural branch to write patches on top of commits not
+already in master.
+A fix for a very old bug or security issue may start off of maint. This isn't
+needed since such fix are backported by the maintainer, though.
+Finally, a work on very active or current development can start from a topic
+next. This clearly means you **need** this topic as a base for what is intended.
diff --git a/docs/HACKING.rst b/docs/HACKING.rst
index 623583f..e21afd7 100644
@@ -2,11 +2,8 @@
.. _OfflineIMAP: https://github.com/nicolas33/offlineimap
Welcome to the `OfflineIMAP`_ project. You'll find here all the information you
@@ -14,6 +11,172 @@ need to start hacking OfflineIMAP. Be aware there are a lot of very usefull tips
in the mailing list. You may want to subscribe if you didn't, yet. This is
where you'll get help.
+Git: Branching Model And Workflow
+In order to involve into OfflineIMAP you need some knowledges about Git and our
+workflow. Don't be afraid if you don't know much, we would be pleased to help
+We use a classical cycle based workflow:
+1. A stable release is out.
+2. Feature topics are sent, discussed and merged.
+3. When enough work was merged, we start the freeze cycle: the first release
+ candidate is out.
+4. During the freeze cycle, no more features are merged. It's time to test
+ OfflineIMAP. New candidates version are released. The more we are late in -rc
+ releases the less patches are merged but bug fixes.
+5. When we think a release is stable enough, we restart from step 1.
+The branching model with use in OfflineIMAP is very near from the Git project.
+We use a topic oriented workflow. A topic may be one or more patches.
+The branches you'll find in the official repository are:
+This comes from a feature offered by Github. We maintain the online home github
+page using this branch.
+If you're not sure what branch you should use, this one is for you. This is the
+mainline. Simple users should use this branch to follow OfflineIMAP's evolution.
+Usually, patches submitted to the mailing list should start off of this branch.
+Patches recently merged are good candidates for this branch. The content of next
+is merged into the mainline (master) at release time for both stable and -rc
+When patches are sent to the mailing list, contributors discuss about them. Once
+done and when patches looks ready for mainline, patches are first merged into
+next. Advanced users and testers use this branch to test last merged patches
+before they hit the mainline. This helps not introducing strong breackages
+directly in master.
+pu stands for "proposed updates". If a topic is not ready for master nor next,
+it may be merged into pu. This branch only help developers to work on someone
+else topic or an earlier pending topic.
+This branch is **not intended to be checkouted**; never. Even developers don't
+do that. Due to the way pu is built you can't expect content there to work in
+any way... unless you clearly want to run into troubles.
+Developers can extract a topic from this branch to work on it. See the following
+section "Extract a topic from pu" in this documentation.
+This is the maintenance branch. It gets its own releases starting from an old
+stable release. It helps both users having troubles with last stable releases
+and users not wanting latest features or so to still benefit from strong bug
+fixes and security fixes.
+Working with Git
+Extract a topic from pu
+pu is built this way::
+ git checkout pu
+ git reset --keep next
+ git merge --no-ff -X theirs topic1
+ git merge --no-ff -X theirs topic2
+ git merge --no-ff -X theirs blue
+ git merge --no-ff -X theirs orange
+As a consequence:
+1. Each topic merged uses a merge commit. A merge commit is a commit having 2
+ ancestors. Actually, Git allows more than 2 parents but we don't use this
+ feature. It's intended.
+2. Paths in pu may mix up multiple versions if all the topics don't use the same
+ base commit. This is very often the case as topics aren't rebased: it guarantees
+ each topic is strictly identical to the last version sent to the mailing list.
+ No surprise.
+What you need to extract a particular topic is the sha1 of the tip of that
+branch (the last commit of the topic). Assume you want the branch of the topic
+called 'blue'. First, look at the log given by this command::
+ git log --reverse --merges --parents origin/next..origin/pu
+With this command you ask for the log:
+* from next to pu
+* in reverse order (older first)
+* merge commits only
+* with the sha1 of the ancestors
+In this list, find the topic you're looking for, basing you search on the lines
+ Merge branch 'topic/name' into pu
+By convention, it has the form <author_initials>/<brief_title>. When you're at
+it, pick the topic ancestor sha1. It's always the last sha1 in the line starting
+by 'commit'. For you to know:
+* the first is the sha1 of the commit you see: the merge commit
+* the following sha1 is the ancestor of the branch checkouted at merge time
+ (always the previous merged topic or the ancien next in our case)
+* last is the branch merged
+ commit sha1_of_merge_commit sha1_of_ancient_pu sha1_of_topic_blue
+Then, you only have to checkout the topic from there::
+ git checkout -b blue sha1_of_topic_blue
+and you're done! You've just created a new branch called "blue" with the blue
+content. Be aware this topic is almostly not updated against current next
More information about the OfflineIMAP-project