Release management of FAI stable using git-svn
==============================================

Michael Prokop <mika@debian.org>

Preface
-------

link:http://fai-project.org/[FAI] uses Subversion (svn) as
version control system but I (Mika) *strongly* prefer
link:http://git-scm.com/[git] over svn because of its nice branch
handling, cherry-picking,....  Therefore I'm using
link:http://www.kernel.org/pub/software/scm/git/docs/git-svn.html[git-svn]
and
link:https://honk.sigxcpu.org/piki/projects/git-buildpackage/[git-buildpackage]
for the release management process. This document describes the
basics of my workflow.

Initial setup
-------------

The FAI subversion repository provides an established branch
layout you can rely on. So first of all check out a full copy of
the svn repos with the branch layout needed for work:

  % git svn clone --trunk=trunk --tags=tags --branches=branches --prefix=svn/ svn+ssh://svn.debian.org/svn/fai fai.git
  % cd fai.git

NOTE: the svn+ssh in above URL is for developers only, use
svn:// for anonymous checkout, but be warned - this will take a
whiiiiiiiiile (roughly ~1 hour), so add "-r $revision" to check
out a specific revision number only.

To be able to push the work also to a specific git hosting
service add it as remote target, like:

  % git remote add grml ssh://git@git.grml.org/fai-stable.git

////////////////////////////////////////////////////////////////////////////////
The stable branch was initially made available through
the subversion repository itself, running:
% svn copy svn+ssh://svn.debian.org/svn/fai/tags/3.3.5 svn+ssh://svn.debian.org/svn/fai/branches/stable/3.4
////////////////////////////////////////////////////////////////////////////////

Workflow regarding a new stable release
---------------------------------------

The workflow usually starts with updating the repository to the
current svn trunk:

  % git checkout master
  % git svn rebase
  [...]
  r6053 = dc2725317c15c2dd6d856e6f596edb57b13ce9ae (refs/remotes/svn/trunk)
  First, rewinding head to replay your work on top of it...
  Fast-forwarded master to refs/remotes/svn/trunk.

Together with other FAI developers we create a list of all svn
revisions that should make it into the new release. Then
cherry-picky all IDs from the svn tree that should make it into
a new stable release of FAI (3.4.x) searching for
"trunk@$SVN_REVISION_ID".

Work happens on a development branch which is based on the stable
branch - so create and switch to it:

  % git checkout -b mika/dev-3.4 stable # mika/dev-3.4 is a non-fast-forward
                                        # throw-away branch for development only

Search for all svn revisions that are considered for inclusion
and review them:

  % git log --all --oneline --grep "trunk@$SVN_REVISION_ID"

Cherry-pick each $COMMIT_ID:

  % git cherry-pick -x $COMMIT_ID # $COMMIT_ID from previous command line

NOTE: On conflicts just fix it ($EDITOR; git reset HEAD $file;
git checkout -- $file; or whatever is necessary) and finally
run 'git commit'.

*Important*: If you do not use '--add-author-from' and
'--use-log-author' the author information gets lost when pushing
changes from git to svn. If so the author information can't be
used when automatically generating the debian/changelog using
git-dch, therefore make sure to configure git accordingly:

  % git config --global svn.useLogAuthor true
  % git config --global svn.addAuthorFrom true

Finally prepare a new snapshot version (v3.4.8~... in this example):

  % cd 3.4
  % mkdir -p .git # make sure git-dch doesn't error out
  % git-dch --ignore-branch --since=v3.4.7 --id-length=7 --meta --multimaint-merge -S
  % vim debian/changelog # adjust if necessary
  % git add debian/changelog
  % git commit -s -m "Release new test version $(dpkg-parsechangelog | awk '/^Version:/ {print $2}')"

Build the source package:

  % git-buildpackage --git-ignore-branch -S

Then the usual Q/A takes place - using cowbuilder for building
the binary package, running lintian on the resulting fai*.changes
file, testing the result.

Release stable release:

  % cd .. # do not be inside 3.4 directory
  % git reset --hard HEAD^
  % git checkout stable
  % git merge mika/dev-3.4
  % git svn dcommit

Finally release new stable version:

  % cd 3.4
  % mkdir -p .git # make sure git-dch doesn't error out
  % git-dch --ignore-branch --since=v3.4.7 --id-length=7 --meta --multimaint-merge --release
  % vim debian/changelog # adjust if necessary
  % git add debian/changelog
  % NEW_VERSION=$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')
  % git commit -s -m "Release new version ${NEW_VERSION}."
  % git svn tag -m "Tagging stable release ${NEW_VERSION}." "${NEW_VERSION}"

Push changes + tags to the stable git repository at git.grml.org
(being the place where the git repository of fai-stable resides):

  % git checkout stable
  % git push grml master # push master (non-stable branch)
  % git push grml stable # push stable (stable branch)
  % git tag -u $DEBSIGN_KEYID -s v3.4.8 -m "release 3.4.8"
  % git push --tags grml

Finally debsign the fai*.changes file upload the package to Debian:

  % dput ftp-master fai...*changes

--------------------------------------------------------------------------------
Document History:

Apr 15 2011: Improve document structure, adjust workflow so git commit
             IDs aren't rewritten after releasing, thanks to Michael
             Tautschnig for feedback.
Jan 29 2011: Change order of git push and git svn dcommit in last section
             (since git svn dcommit uses git svn rebase internally).
Dec 23 2010: Add "git svn rebase" before "git svn dcommit".
Okt 15 2010: Add "git rebase grml/stable" before "git push grml stable".
Okt 06 2010: Replaced --git-debian-branch=... cmdline option with
             --git-ignore-branch, thanks to Guido Guenther.
Okt 02 2010: First revision.
--------------------------------------------------------------------------------