From e7439b5d774e62a9477f67ad3d3bc2bb3c3a5657 Mon Sep 17 00:00:00 2001 From: Nicolas Sebrecht Date: Sat, 7 May 2011 14:37:23 +0200 Subject: [PATCH 1/2] doc: introduce a new HACKING file This aims to help newcomers to be very fast to involve into the project. Signed-off-by: Nicolas Sebrecht --- docs/HACKING.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/HACKING.rst diff --git a/docs/HACKING.rst b/docs/HACKING.rst new file mode 100644 index 0000000..623583f --- /dev/null +++ b/docs/HACKING.rst @@ -0,0 +1,23 @@ +.. -*- coding: utf-8 -*- + +.. _OfflineIMAP: https://github.com/nicolas33/offlineimap + +.. contents:: +.. sectnum:: + +=================== +HACKING OFFLINEIMAP +=================== + +Welcome to the `OfflineIMAP`_ project. You'll find here all the information you +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. + +=== +API +=== + +API is documented in the dev-doc-src directory using the sphinx tools (also used +for python itself). This is a WIP. Contributions in this area would be very +appreciated. From 9a9379f8f33dab376aafb6fdc9f3b0f8b04227f8 Mon Sep 17 00:00:00 2001 From: Nicolas Sebrecht Date: Sun, 8 May 2011 17:03:58 +0200 Subject: [PATCH 2/2] add documentation about Git Signed-off-by: Nicolas Sebrecht --- 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 --- a/docs/FAQ.rst +++ b/docs/FAQ.rst @@ -355,6 +355,22 @@ accounts. Miscellaneous Questions ======================= +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:: do ( exec /usr/bin/offlineimap -u Noninteractive.Quiet ) sleep 60 # prevents extended failure condition + + +Contributing +============ + +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 +page. + +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 +https://github.com/nicolas33/offlineimap/blob/master/SubmittingPatches.rst#readme +. + +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 --- a/docs/HACKING.rst +++ b/docs/HACKING.rst @@ -2,11 +2,8 @@ .. _OfflineIMAP: https://github.com/nicolas33/offlineimap -.. contents:: -.. sectnum:: - =================== -HACKING OFFLINEIMAP +Hacking 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. +.. contents:: +.. sectnum:: + + +================================= +Git: Branching Model And Workflow +================================= + +Introduction +============ + +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 +you. + +Release cycles +============== + +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. + + +Branching model +=============== + +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: + +* gh-pages +* master +* next +* pu +* maint + +gh-pages +-------- + +This comes from a feature offered by Github. We maintain the online home github +page using this branch. + +master +------ + +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. + +next +---- + +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 +releases. + +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 +-- + +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. + +maint +----- + +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 +like:: + + Merge branch 'topic/name' into pu + +By convention, it has the form /. 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 + +Giving:: + + 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 +branch. ,-) + + === API ===