Git transition checklist

[Eric S. Raymond]

This post rounds up all the issues I know about with the bzr to git
changeover and their current state.  A revised transition checklist
is included at the end.

Eli Zaretski recommended, and Stefan Monnier endorsed, the following
preparatory steps for the transition to git:

> 5. Have the procedures and the recommended workflows described on the
>    wiki, similar to what was done with bzr migration.

That is now done.  I have created two new pages on EmacsWiki,
GitForEmacsDevs and GitQuickStartForEmacsDevs. These are adapted from
the corresponding *Bzr* pages but describe git commands to perform
equivalent operations.

The only omission is that I left out the git equivalent of bzr bundle.
There is such a feature in git, but it is one of the historical
fossils in the system and rarely enough used that I wouldn't want to
rely on it not bitrotting.  Git practice has moved decisively to (a)
mailing around patch sets produced by git format-patch, and (b)
github/gitorious-style merge requests.

An interesting side effect of doing this translation, by the way, is
that I now know the exact git-command equivalents for the recommended
workflow in Bazaar.  Rather to my surprise, the git procedures are
simpler!

I'm surprised at this because Bazaar, whatever its other failings, had
a reputation as being simpler to use than git which I believed was
deserved. But, at least for the workflows described, git avoids so
much complexity and ceremony by not having the branch-vs.-repo
distinction that the gain from this swamps git's other UI
shortcomings.

> 6. Describe (and test if needed) the procedure for migrating local
>    bzr branches into git without losing history (yes, I have a
>    couple in the works), and describe that on the wiki as well.

That's easy.  Make a patch sequence from your bzr branch using sendto
- the format is compatible with GNU patch.  git checkout the branch
name at the equivalent point in the git repo.  Use GNU patch to apply.
Fill in change comments as required.

I don't think this really belongs on the wiki, as it's a one-shot
transition issue probably affecting only a few people and possibly
only you. But if you think it needs describing there, go to it.

> 7. What about the mail messages to emacs-diffs mailing list?  That
>    should be working as well, and support pushes to non-trunk
>    branches.

That is trivial in git.  Andreas can set it up in minutes.  I could too,
but I don't have write access to the repo hook files.

> 8. There's the emacs-bzr-version whose value gets copied into the bug
>    reports.  This should be replaced by the suitable git equivalent,
>    or else the bug reports (of which we have quite a few each day)
>    will not identify the version correctly.

Proof of concept (tested):

(defun emacs-repository-get-version (&optional dir)
  "Try to return as a string the version-control revision of the Emacs sources.
Value is nil if the sources do not seem to be under version
control, or if we could not determine the revision.  Note that
this reports on the current state of the sources, which may not
correspond to the running Emacs.

Optional argument DIR is a directory to use instead of `source-directory'."
  ;; This is the only function that knows what VCS the Emacs sources are under.
  (let ((here default-directory))
    (cd (or dir (setq dir source-directory))) 
    (message "Waiting for git...")
    (with-temp-buffer
      (if (zerop
           (call-process "git" nil '(t nil) nil "describe" "--tags"))
         (buffer-string)))
    (cd here)))

Replacing the function emacs-bzr-get-version with this will rectify a
design error; it callers knew the string "bzr", which they should not have -
they didn't care what the VCS was as long as they could back some 
version cookie to embed in bug reports.

This code is simpler than emacs-bzr-get-version because "git describe" is
very fast - there's no need to avoid calling it for better performance.

The change to integrate this and fix its callers is easy, five minutes'
work which I will cheerfully do immediately after the repo switchover.
No need to do it before as it really only becomes crucial to have this
working for the next point release.

Stefan Monnier added these:

- Improve vc-git.el so that it can automatically enable smerge-mode when
  opening a conflicted file and (probably conditional on a config var)
  mark the file as "not conflicted any more" when saving with no
  remaining diff3 markers.
  This currently works in vc-bzr.el (and vc-svn.el as well, IIRC).

- Improve vc-git.el with vc-git-conflicted-files so that
  vc-find-conflicted-files works for Git as well.

Thierry Volpiatto pointed out that these issues are addressed now:
"You can use git-mergetool with ediff-merge for this" he said, 
and gave a recipe.

Better cross-VCS integration of smerge mode would be nice but is not a
git-vs.bzr issue - rather it's a feature request against VC which,
as VC's maintainer, I take note of and will address after the switchover.

- Release 24.4 (i.e. I'd rather not deal with the move before we
  release 24.4).

That seems completely reasonable to me.

Nobody else explicitly suggested any additional preconditions. Andreas
Schwab did, however, observe this:

>A good way to identify a git branch is to use git describe.  However it
>prefers to have an annotated (release) tag available to base on, which
>we currently don't have (bzr doesn't have the concept of annotated
>tags).

This should be fixed.  Each Emacs release should be marked with an 
annotated tag, and annotations should be retconned onto the historical
releases.  This is basic good Git practice; it helps guard against attacks
by trojaned versions of the public releases.

So, here is the revised operation sequence for the changeover.

0. Before changeover, we prepare a shellscript that creates annotated
   cryptosigned tags for the historical versions. (This will require
   Stefan to create an "Emacs maintainer" GPG identity if none exists.)

1. Wait on 24.4 release and Stefan's go signal.

2. Andreas announces on the dev list that the changeover is beginning.

3. Andreas turns off bzr commit mirroring (and disables the bzr repo).

4. Andreas enters a small documentation commit recording the changeover.

5. Andreas installs a commit hook that mails notifications to the emacs-diffs
   mailing list

6. Stefan applies the script to make cryptosigned historical release tags.

7. Andreas announces on the dev list that the git repo is live for
   developer pushes.

8. I replace emacs-bzr-version with emacs-repository-get-version.

9. I mark the wiki pages on Bzr obsolete and update the Git ones.

10. I will do the work required to update /etc and /admin to reflect
    git use over the following few days.

11. (Later, lower priority.) I arrange better cross-VCS integration of smerge
    in vc.el.

That's it, I think.  Currently I see only two blockers on the process:
(a) 24.4 needs to ship, and (b) somebody needs to write the script to 
map the existing lightweight release tags to cryptosigned annotated tags. 
I'll work on that.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>

Our society won't be truly free until "None of the Above" is always an option.