Merge branch 'ns/working-with-git' into next
This commit is contained in:
Nicolas Sebrecht
commit
bdeaebbb7d
55
docs/FAQ.rst
55
docs/FAQ.rst
@ -383,6 +383,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?
|
||||
-----------------------------------------------
|
||||
|
||||
@ -424,3 +440,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.
|
||||
|
||||
|
||||
186
docs/HACKING.rst
Normal file
186
docs/HACKING.rst
Normal 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.
|
||||
Loading…
Reference in New Issue
Block a user