[sunzi/development] README.maint: revisit the branching + release steps

[Jan Pokorný]

commit 3666b73a8700b1553178d70a18bc171d831bcece
Author: Jan Pokorný <jpokorny(a)redhat.com&gt;
Date:   Sat Mar 17 13:44:31 2012 +0100

    README.maint: revisit the branching + release steps
    
    Signed-off-by: Jan Pokorný <jpokorny(a)redhat.com&gt;

 README.maint |   72 +++++++++++++++++++++++++++++++++++++--------------------
 1 files changed, 47 insertions(+), 25 deletions(-)
---
diff --git a/README.maint b/README.maint
index 7045881..ec0b444 100644
--- a/README.maint
+++ b/README.maint
@@ -14,69 +14,91 @@ See also `README.contrib`.
 
 Branches
 --------
-* `master`      -> current version maintenance
-* `development` -> upcoming version development
-* longer-term support versions (bases for distro releases) have own
-  branches (can be created ex-post, return to specific tag and fork it)
-* ...
+* `master`         -> current version maintenance
+* `development`    -> upcoming version development
+* release branches -> on-demand forks from `master` (as per tag) treated
+                      the same way as `master` itself
 
 Work on an isolated bug/feature happens on a separate branch that can
 be either public (same/another repo) or local only, then pushed as
 reasonable-sized patches to the respective branch:
 
-new feature -> `development`
-bugfix      -> `master` + `development` (depending on what is applicable)
-(or long-term support version, indeed)
+new feature            -> (feature branch ->) `development`
+bugfix                 -> release branch(es) -> `development`
+refactorings, cleanups -> `development` (if atomic)
 
-IOW, `master` should never be broken.
+IOW, `master` should always be production-ready and its history should be
+a bit cleaner than `development`, which is still quite clean as checkpoint
+commits for features/bugfixes are matter of feature/bugfix branches
+(well, it will be after the early phase is over).
 
-When new upstream release to be done, merge `development` into `master`,
-release is made from `master` (incl. making a tag, see II.A.), then
+When new upstream release to be done, the preparation is made in
+`development`, changes forwarded into `master` (see II.A.), then
 `development` branch is used primarily again.
 
+See also:
+`<http://nvie.com/posts/a-successful-git-branching-model/>`_
+`<http://sandofsky.com/blog/git-workflow.html>`_
+
 
 II. Managing Python releases
 ============================
 
 A. Making a new upstream release
 --------------------------------
-1. Make sure everything intended is in upstream git repo and ready.
+1. Make sure everything intended is in `development` and ready
+   (meaning the feature branches has been forwarded to `development`).
    See IV. if you want to update third-party bundles for release
-   (note that this substep should be done much earlier and tested).
-2. Take a look at the changes since the last version/tag::
+   (note that this substep should be done much earlier and tested,
+   but always in `development` branch).
+
+2. Forward changes in `development` to `master` (being on `development`)::
+
+    $ git rebase --interactive master
+    # select which commits to preserve as such and which to dissolve
+    # to large changes (various little cleanups into a single one, etc.)
+    # NOTE: first forward to `master` will probably be different
+    #       (git checkout master; git merge --squash development?)
+
+(2b. test if rebase went well, if not, return to 1.)
 
-    $ git whatchanged PREVTAG.. --oneline # or silimar
+3. Tag the release::
 
-   then pick the most important items and add them briefly
-   to `CHANGES.txt` denoting the upcoming version
-   (TODO: format to be established)
-3. Commit `CHANGES.txt` with `sunzi-X.Y.Z` commit message.
-4. Tag the release::
+    $ git tag release-X.Y.Z  # TODO: options (should be annotated?)
 
-    $ git tag sunzi-X.Y.Z # TODO: options (should be annotated?)
+4. Take a look at the changes since the last version/tag (based on 2.)::
 
-5. Finally, create a tarball(s)::
+    $ git whatchanged PREVTAG.. --oneline >> CHANGES.txt # or silimar
+    $ vim CHANGES.txt  # if needed
+    # NOTE: CHANGES.txt is not intended as a part of the repo, but may be
+    #       part of the package or distributed along it as separate file
+
+5. Create a tarball(s)::
 
     $ python setup.py tarball
     # or alternatively:
     $ ./setup tarball
 
 6. Postprocess the tarball(s) [TODO: script would be handy]
-   - tar.gz -> tar.xz
+   - tar.gz -> tar.xz (TBD: is it worth?)
    - create sha256 checksums (tar.* + CHANGES.txt)
    - upload release files to fedorahosted.org hosting, e.g.::
 
-    scp sunzi-0.1.0.* CHANGES.txt fedorahosted.org:sunzi
+    $ scp sunzi-0.1.0.* CHANGES.txt fedorahosted.org:sunzi
 
    NOTE: generating `download_url` automatically -- follow this URL!
    NOTE: gpg signing integrated with `upload` command of setuptools
    TODO: include git log between versions? E.g., CHANGES-0.1.0.txt
    TODO: upload to PyPI?
+
 7. Send announcements, etc., whatever suitable.
 
+If in any stated step a defect was detected, start from 1., incrementing
+last version number.
+
 B. Make a scratch release/developing in-place
 ---------------------------------------------
-1. As easy as this (version on non-tag commit should be set
+1. As easy as this (version on non-tagged commit should be set
    according to the last tagged version + shortened commit hash)::
 
     $ ./setup release # release