[lmi] Proposed workflow for proprietary repository

[Greg Chicares]

* Preliminary git configuration

Use your name and email address instead of mine. This "user" identity
will be embedded in patches we send among ourselves.

  git config --global user.name "Gregory W. Chicares"
  git config --global user.email address@hidden

The 'color.ui' line is optional. Replace "auto" with "false" to turn
color off if you prefer.

  git config --global color.ui auto

This setting simply suppresses an informational message from 'git push'
that describes the way git used to work, which is of no interest to us
(works with git-2.7.0; invalid for git-1.7.10.4):

  git config --global push.default simple

* Create patch directories

Even though git doesn't care where we store patches, they're crucial
for our workflow, so we may as well decide where to keep them. We
already use /opt/lmi/ for all lmi work, so let's create subdirectories
there:

  mkdir --parents /opt/lmi/proprietary-patches/in
  mkdir --parents /opt/lmi/proprietary-patches/out

* Setting up a working copy

We start with a "blessed" git repository (shared in email) that has
been migrated from svn. Let's save the emailed tarball in /opt/lmi/ ,
extract it there...

  cd /opt/lmi
  tar -xjvf proprietary-blessed-repository.tar.bz2

...and make a working copy:

  git clone file:///opt/lmi/blessed/proprietary

The resulting /opt/lmi/proprietary directory looks very much like a
checked-out working copy of the old svn repository. Instead of .svn/
it has .git/ , but its subdirectories are otherwise identical: they
have the same names and exactly the same contents.

Compare the sha1sums, which should certainly be identical:

  cd /opt/lmi/blessed/proprietary; git rev-parse HEAD
b5f2b3d4cfd179bbe4ac433d5bbe86d922bec2dc
  cd /opt/lmi/proprietary; git rev-parse HEAD
b5f2b3d4cfd179bbe4ac433d5bbe86d922bec2dc

In principle we only need to create a working copy once. However,
because we're learning git, let's use this one as a throwaway sandbox.
It'll only take ten seconds to create a fresh copy later for real work.

* Applying an email patch

Suppose you receive two patches in email: one inline [0], and one as an
attachment. We'll try both ways, and then if one seems easier, we can
choose that for future work. [I think attachments will prove easier.]

Copy the inline patch between the "8<" scissors lines to the clipboard
in whatever way your email program does that. Then paste it into a file:

  cat >/opt/lmi/proprietary-patches/in/first.patch
  [paste from clipboard]
  [press Ctrl-D]

[I pasted directly into 'cat' because the usual here-document syntax
  cat >/opt/lmi/proprietary-patches/in/first.patch <<\EOF
causes any tab characters to be eaten: apparently it's interpreted as a
request for command completion, as though the Tab key had been pressed.
I see that problem on Debian-7 with zsh-4.3.17, but not on current
Cygwin with zsh-5.1.1 .]

Save the attachment
  /opt/lmi/proprietary-patches/in/0002-Replace-svn-with-git.patch
. (That process seems easier, but let's test it to
make sure it's at least as robust.) Now apply the patches:

  cd /opt/lmi/proprietary
  git rev-parse HEAD
b5f2b3d4cfd179bbe4ac433d5bbe86d922bec2dc
  git am --committer-date-is-author-date \
    /opt/lmi/proprietary-patches/in/first.patch
  git rev-parse HEAD
5f876b0a61554fe59979ad7620ab61cc7dc0dd27
  git am --committer-date-is-author-date \
    /opt/lmi/proprietary-patches/in/0002-Replace-svn-with-git.patch
  git rev-parse HEAD
5e4e7fd8ab35a196cd1f5cc3c5b981c960664226

Our goal is to maintain synchronized but separate repositories, with no
central server. To make sure we're synchronized, we'll compare sha1sums.
To make the sha1sums match, we need '--committer-date-is-author-date';
otherwise, they'd depend on the particular times two different people
ran the 'git am' command, which would almost certainly differ--see:
  http://lists.nongnu.org/archive/html/lmi/2016-03/msg00004.html
The sha1sums given by the 'git rev-parse HEAD' commands above match
those on the first line of each patch. Along with the starting sha1sum
of the migrated svn repository, they match git's log, too:

  git log -3 | grep '^commit'
commit 5e4e7fd8ab35a196cd1f5cc3c5b981c960664226
commit 5f876b0a61554fe59979ad7620ab61cc7dc0dd27
commit b5f2b3d4cfd179bbe4ac433d5bbe86d922bec2dc

[Ideally, we would like to have a command to apply patches safely.
In the case of 'first.patch' above, it would (1) check the HEAD sha1sum,
and (2) determine whether applying the patch would result in the sha1sum
given on the first line of the patch; then apply the patch only if both
match, otherwise printing a diagnostic but making no change to the
working copy. Perhaps (1) is the only meaningful check: if it succeeds,
then it should be impossible for (2) to fail, though (2) should then be
so easy that there's no reason not to do it. But git-generated patches
don't provide the pre-commit HEAD; we'd have to do that ourselves.
Alternatively, if condition (2) holds, then (1) is (probabilistically)
guaranteed; but 'git apply --check' doesn't give the sha1sum that would
result from applying the patch. Vadim, what do you think?]

* Pushing from working copy to blessed bare repository

[Motivation: if two people's sha1sums diverge for any reason, and each
has maintained a local blessed repository with all the shared changes,
then a working copy can easily be regenerated by 'git clone'.]

After applying a set of patches that you sent or received in email,
push it to your blessed repository. For example, after applying the
two patches above, the status should look like this:

  git rev-parse HEAD
5e4e7fd8ab35a196cd1f5cc3c5b981c960664226
  git status
# On branch master
# Your branch is ahead of 'origin/master' by 2 commits.
#
nothing to commit (working directory clean)

Now push the patches:

  git push
...
To file:///opt/lmi/blessed/proprietary
   b5f2b3d..5e4e7fd  master -> master

As expected, b5f2b3d... has advanced to 5e4e7fd... .

* Creating a patch to send in email

Suppose you object to word four in this sentence in 'src/ChangeLog':
  Use the actual commit time, so that others can confidently match log
  entries against git changes. Run 'make check_concinnity' before
because we're using '--committer-date-is-author-date', so you want to
change "commit" to "author". Edit the file, make the change, and save
it. Then, to see pending changes:

  git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   src/ChangeLog
#
no changes added to commit (use "git add" and/or "git commit -a")

If you want to see what effect the commit would have:

  git commit src/ChangeLog --dry-run
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   src/ChangeLog

Let's commit it:

  git commit src/ChangeLog -m"Change 'commit' to 'author'"
[master 8b50a18] Change 'commit' to 'author'
 1 file changed, 1 insertion(+), 1 deletion(-)

[your sha1sum will differ, because you're the "author" and you didn't
commit at exactly the same time as I did; but mine will match yours
when I apply your patch with '--committer-date-is-author-date'...mail
it to me so I can verify that please]

and create a patch:

  git format-patch origin --output-directory=/opt/lmi/proprietary-patches/out
/opt/lmi/proprietary-patches/out/0001-Change-commit-to-author.patch

The name of the new patch file is printed. That's the file to attach
when emailing your patch (assuming, as is likely, that we decide to use
attachments instead of writing patches inline).

Lastly, push this change to your blessed repository as above:

  git rev-parse HEAD
8b50a1813aaf573d1f86181b5a25715fac338803
  git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit, working directory clean
  git push
To file:///opt/lmi/blessed/proprietary
   5e4e7fd..8b50a18  master -> master

* Forging ahead

Now that we're done experimenting, it's time to clear the table:
  rm -rf /opt/lmi/proprietary/
  rm -rf /opt/lmi/blessed/proprietary
  rm -rf /opt/lmi/proprietary-patches/in
  rm -rf /opt/lmi/proprietary-patches/out
then repeat the setup steps above so we can begin real work.

---------

[0] "patches in email: one inline"

--------------------------------- 8< ---------------------------------
>From 5f876b0a61554fe59979ad7620ab61cc7dc0dd27 Mon Sep 17 00:00:00 2001
From: "Gregory W. Chicares" <address@hidden>
Date: Sat, 5 Mar 2016 17:46:42 +0000
Subject: [PATCH 1/2] Remove $Id$ from change log

---
 src/ChangeLog | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/ChangeLog b/src/ChangeLog
index 40e2f28..365f49d 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -4,8 +4,6 @@
 //
 // http://savannah.nongnu.org/projects/lmi

-// $Id$
-
 MAINTENANCE

 Please write entries this way:
--
2.7.0
--------------------------------- >8 ---------------------------------