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