Merge branch 'ns/working-with-git' into next

This commit is contained in:
Nicolas Sebrecht 2011-05-09 19:52:39 +02:00
commit bdeaebbb7d
2 changed files with 241 additions and 0 deletions

View File

@ -383,6 +383,22 @@ accounts.
Miscellaneous Questions 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? Why are your Maildir message filenames so long?
----------------------------------------------- -----------------------------------------------
@ -424,3 +440,42 @@ written in Korn, so youll need ksh, pdksh, or mksh to run it::
do do
( exec /usr/bin/offlineimap -u Noninteractive.Quiet ) ( exec /usr/bin/offlineimap -u Noninteractive.Quiet )
sleep 60 # prevents extended failure condition 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.

186
docs/HACKING.rst Normal file
View File

@ -0,0 +1,186 @@
.. -*- coding: utf-8 -*-
.. _OfflineIMAP: https://github.com/nicolas33/offlineimap
===================
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.
.. 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 <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
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
===
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.