Re: Access to CVS

Re: Access to CVS

[Oliver Kiddle]

Aaron Schrab wrote:
> The `--ff-only` option is only somewhat useful here.  It merely causes 
> the merge to be aborted if it can't be done without creating a merge 
> commit, in which case some other method of bringing in those changes 
> would need to be tried.

I was trying to keep it reasonably brief. Feel free to suggest
alternative wording.

Aaron Schrab wrote:
> At 07:37 -0800 13 Dec 2012, Bart Schaefer <schaefer@brasslantern.com> wrote:
> >Is there any way to actually enforce this?
> 
> If the main git repository were fully under our control, yes, a hook 
> could be setup there to reject pushes which introduce merge commits.  

For sourceforge, we can get at the repository using the shell access.
The documentation mentions commit email hooks so others are probably
possible. That said, I'm not sure it would be wise because it would also
block merges from public feature branches.

Peter Stephenson wrote:
> It might be useful to give a sample list of explicit git commands to use
> at each stage, in particular what you'd do for an initial commit, for
> updating the commit with the mailing list ID, for any kind of trickery
> to reduce the number of commits that get pushed, and for pushing it back
> (as this is for those new to git you can assume the relationship between
> the local archive and the remote master is simple and let the git gurus
> do the clever stuff).

Is that a suggestion for the contents of Etc/zsh-development-guide or
just a case that it'd be useful. I'm assuming the latter - it's not like
we have an introduction to CVS, autoconf, C etc in the file. Anyway, in
that case it seems Phil and Frank have already answered this.

Oliver

Re: Access to CVS

[Peter Stephenson]

On Fri, 14 Dec 2012 15:44:22 +0100
Oliver Kiddle <okiddle@yahoo.co.uk> wrote:
> Peter Stephenson wrote:
> > It might be useful to give a sample list of explicit git commands
> > to use at each stage, in particular what you'd do for an initial
> > commit, for updating the commit with the mailing list ID, for any
> > kind of trickery to reduce the number of commits that get pushed,
> > and for pushing it back (as this is for those new to git you can
> > assume the relationship between the local archive and the remote
> > master is simple and let the git gurus do the clever stuff).
> 
> Is that a suggestion for the contents of Etc/zsh-development-guide or
> just a case that it'd be useful. I'm assuming the latter - it's not
> like we have an introduction to CVS, autoconf, C etc in the file.
> Anyway, in that case it seems Phil and Frank have already answered
> this.

If there was a compact enough summary to go in the development guide,
that would be great, though it's not crucial.  The problem is git allows
a zillion different ways of doing it whereas in CVS you were restricted
to committing what you've changed, and that was it.

I'm still hoping for a simple, straightforward list of the basic
commands you'd need to use *not* involving the manifold ramifications of
branches here, there and everywhere.  Presumably this isn't more than
half a dozen commands or so.

pws

Re: Access to CVS

[Phil Pennock]

On 2012-12-14 at 15:09 +0000, Peter Stephenson wrote:
> I'm still hoping for a simple, straightforward list of the basic
> commands you'd need to use *not* involving the manifold ramifications of
> branches here, there and everywhere.  Presumably this isn't more than
> half a dozen commands or so.

% $VISUAL file1.c file2.c new-file3.c
% git add new-file3.c
% git commit -a
% git push

"git commit -a" automatically finds files which are tracked and have
been modified, but doesn't pick up files newly tracked.  "git add"
starts tracking a file.

"git commit -a -i new-file3.c" should also add the file.

If you want to be more selective, then for each file changed, "git add"
it to stage it in the index for the next commit, then just "git commit"
which will only commit the manually-staged files.

"git push" assumes that you're on the master branch and the repository
was created by cloning it from some place, with default options.

Try to get the most recent version of git you can, they're in the middle
of switching "git push" semantics to be saner/safer/cleaner by default
("only push the current branch, and only if this branch exists on the
remote server") and you probably want this new default.  Git 1.8+

Everything else is about building on that.  It's just that with an
existing repository and code-base where complexity is already an issue,
you're in the unfortunate position of trying to avoid making the
repository complicated and so folks are suggesting ways to minimise the
history complexity of the repository, and so your learning curve is even
steeper.  I faced the same problems when Exim switched.  :-/

-Phil

Re: Access to CVS

[Peter Stephenson]

On Fri, 14 Dec 2012 14:29:45 -0500
Phil Pennock <zsh-workers+phil.pennock@spodhuis.org> wrote:
> On 2012-12-14 at 15:09 +0000, Peter Stephenson wrote:
> > I'm still hoping for a simple, straightforward list of the basic
> > commands you'd need to use *not* involving the manifold ramifications of
> > branches here, there and everywhere.  Presumably this isn't more than
> > half a dozen commands or so.
> 
> % $VISUAL file1.c file2.c new-file3.c
> % git add new-file3.c
> % git commit -a
> % git push

Thanks, that's pretty much what I was expecting...

In this (ultra-simple) case, presumably we're assuming the mailing list
link gets added immediately in the commit log.

If anybody thinks that above *isn't* the basic sequence, or that their
own preferred procedure is something other than a more sophisticated
form of theabove, it would be good to hear.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: Access to CVS

[Wayne Davison]

[-- Attachment #1: Type: text/plain, Size: 1104 bytes --]

On Sat, Dec 15, 2012 at 10:09 AM, Peter Stephenson <
p.w.stephenson@ntlworld.com> wrote:

> If anybody thinks that above *isn't* the basic sequence, or that their
> own preferred procedure is something other than a more sophisticated
> form of theabove, it would be good to hear.
>

It's always good to view your own commit to double-check it, and to also to
check for missed files.  So I'd suggest adding "git show" after "git commit
-a" (that lets you look over your latest commit) and "git status" (lets you
look for uncommitted files).  And then, right before the "git push", toss
in "git pull --rebase" to remind folks to check for remote changes prior to
pushing (using --rebase instead of merge).  Finally, it would be good to
mention tags somewhere, since it requires a separate "git push --tags" if
you want your tags to become public, but I doubt we'd want to mention it in
the basic sequence, since it's likely we just want things like release tags.

% $VISUAL file1.c file2.c new-file3.c
% git add new-file3.c
% git commit -a
% git show
% git status
% git pull --rebase
% git push

..wayne..

Re: Access to CVS

[Aaron Schrab]

At 11:07 -0800 15 Dec 2012, Wayne Davison <wayned@users.sourceforge.net> wrote:
>It's always good to view your own commit to double-check it, and to 
>also to check for missed files.  So I'd suggest adding "git show" after 
>"git commit -a" (that lets you look over your latest commit)

It's even nicer to look it over before committing.  For that I've done:

  git config --global alias.ci 'commit -v'

Then I always use `git ci` rather than `git commit`.  This causes the 
diff of what I'm going to be committing to be included in the file where 
I create the commit message, so I can look it over there.

This can also help for editing the commit message by having modified 
functions included in the edit buffer so that their names are available 
for completion if I want to mention them in the message.

Re: Access to CVS

[Phil Pennock]

On 2012-12-14 at 14:29 -0500, Phil Pennock wrote:
> "git commit -a" automatically finds files which are tracked and have
> been modified, but doesn't pick up files newly tracked.  "git add"
> starts tracking a file.

*sigh* Dumbass mis-statement on my part, sorry.

"git commit -a" doesn't pick up newly created files, because they're not
tracked (except just enough to say "not tracked" and to be handled by
commands like "git stash").

> If you want to be more selective, then for each file changed, "git add"
> it to stage it in the index for the next commit, then just "git commit"
> which will only commit the manually-staged files.

To be clear: "git add" is not "add tracking this new file to the
repository", it's "add this file to the index of changes to be in the
next commit", where such a change _might_ be the creation of a new file,
or might simply be "I changed it, include it".

-Phil

Re: Access to CVS

[Bart Schaefer]

On Dec 16,  4:50am, Phil Pennock wrote:
}
} *sigh* Dumbass mis-statement on my part, sorry.

OK, I now count about ten messages *since* Oliver's summary in 30877 that
have useful information about git procedures applicable to using it for
zsh in conjuction with the mailing list for patches.

Anybody want to summarize *again*?

As PWS noted, there really wasn't much reason for zsh-development-guide
to have this kind of detail for CVS, because CVS doesn't have very many
options for how to use it.  Git is complex enough that I think we should
give additional guidance to avoid missteps.

Access to CVS

[Vin Shelton]

Can anyone access zsh.cvs.sourceforge.net?  I'm seeing:

cvs [update aborted]: reading from server: Connection reset by peer

when I try to do a cvs update.

Regards,
  Vin

Re: Access to CVS

[Phil Pennock]

On 2012-12-04 at 17:32 -0500, Vin Shelton wrote:
> Can anyone access zsh.cvs.sourceforge.net?  I'm seeing:
> 
> cvs [update aborted]: reading from server: Connection reset by peer
> 
> when I try to do a cvs update.

Works with :ext: stuff such that it's going over SSH.

The rsync interface for cloning the CVS tree is working fine.  My local
copy of the tree is intact and updates fine.  (It does so via cron,
normally, but I just forced a zsh-specific verbose run and rsync ran
without issues).

Perhaps the CVS-on-wire protocol server has issues; can you switch to
SSH-based access?

(zsh is about the only thing I still use CVS for; FWIW, if folks do ever
 decide to switch, I don't much care which DVCS is chosen (git, hg,
 whatever) but would appreciate such a switch.  Any hope of the git
 mirror becoming the official master repo?)

-Phil

Re: Access to CVS

[Oliver Kiddle]

Phil Pennock wrote:
> (zsh is about the only thing I still use CVS for; FWIW, if folks do ever
>  decide to switch, I don't much care which DVCS is chosen (git, hg,
>  whatever) but would appreciate such a switch.  Any hope of the git
>  mirror becoming the official master repo?)

I gather that the current status is that we just need a git expert
willing to take the lead on that.

There's also a couple of things that need sorting out:

Associating commits to mailing list numbers. This amounts to using git
notes (see workers/30123) so probably just needs a clear convention.
Perhaps we could use a hook script to enforce it on the master 
repository.

Generating the patch level some other way. Using the git hash (or
first eight characters of it) would be easy enough but you would lose
the ability to compare patch levels and assert which is newer or
older. I don't think there is much we can do about that. While git
sort-of supports $Id$ style strings it seems that isn't what we should
do. For some ideas on what git people appear to recommend, see:
http://stackoverflow.com/questions/1792838/enable-ident-string-for-git-repos
http://git.kernel.org/?p=git/git.git;a=blob;f=GIT-VERSION-GEN;hb=HEAD

Does anyone have any idea whether sourceforge makes it easy for an
individual to publish forked/cloned git repositories in the manner of
github or bitbucket? Or is it better to just keep development
branches/threads in the main repository.

Oliver

Re: Access to CVS

[Phil Pennock]

On 2012-12-05 at 01:33 +0100, Oliver Kiddle wrote:
> Phil Pennock wrote:
> > (zsh is about the only thing I still use CVS for; FWIW, if folks do ever
> >  decide to switch, I don't much care which DVCS is chosen (git, hg,
> >  whatever) but would appreciate such a switch.  Any hope of the git
> >  mirror becoming the official master repo?)
> 
> I gather that the current status is that we just need a git expert
> willing to take the lead on that.
> 
> There's also a couple of things that need sorting out:
> 
> Associating commits to mailing list numbers. This amounts to using git
> notes (see workers/30123) so probably just needs a clear convention.
> Perhaps we could use a hook script to enforce it on the master 
> repository.

Biggest problem is if the change in the mail doesn't exactly match the
files being patched, in which case there's not identifying information
in the mail to figure out the commit.  If the person grabbing the patch
uses "git note" manually, or as a filter to grab X-Seq, then it works.

*If* the patch in the mail is cleanly applying to the exact same files,
then you can use a cron job, taking recent mails from zsh-workers, so
that there's as much decoupling as possible, and zsh-workers vs
git-commit ordering doesn't matter.

Taking a git patch from an email and turning it into full blobs of the
new version of a file (ie, the id of the new content):

 cat mail-file | \
 pcregrep -o1 -M '^index\s+[0-9A-Fa-f]+\.\.([0-9A-Fa-f]{6,})\s\d+\r?\n--- a/' \
 | git cat-file --batch-check

Output is lines of "${checksum-id} blob ${blobsize}"

Use with:
  https://github.com/jwiegley/git-scripts/blob/master/git-find-blob
and find the earliest commit id where a tree referenced the blobs from
the mail.

It's horrendously inefficient, but if you're constraining it to
--since="5 days ago" to allow for maximum discrepancy, then you've
bounded the O(N^2) to very small values of N.

Scenario 1 (rarer):
 * commit, then mail out the patch to say "er, I did this"
   * mail is processed, finds the commit, you have five days to get
     around to mailing

Scenario 2:
 * mail out, then commit.  The mail is held until successfully matched.
   Once the commit is made, the mail is deleted.  The cronjob presumably
   runs every hour or so, thus --since="5 days ago" is about 4days23hrs
   generous

Scenario 3:
 * no git diffs in the mail; log that nothing found for that X-Seq:,
   delete

Ickiest bit is the reporting for mails older than a week which haven't
been matched, and the commits without the note.  That requires HTML
skills to make the pretty web-page people want when tracking down what
got lost.  ;)

> Generating the patch level some other way. Using the git hash (or

There's what we do in Exim:
  http://git.exim.org/exim.git/blob/HEAD:/src/scripts/reversion
around line 40.


I can't commit time for a _project_ to complete any of this until some
time next year.  Sorry.  :(  Folks are still waiting on revamped
regex/multibyte-counting fixes from me.  :(

-Phil

Re: Access to CVS

[Bart Schaefer]

On Dec 4, 10:14pm, Phil Pennock wrote:
} Subject: Re: Access to CVS
}
} On 2012-12-05 at 01:33 +0100, Oliver Kiddle wrote:
} > Associating commits to mailing list numbers. This amounts to using git
} > notes (see workers/30123) so probably just needs a clear convention.
} > Perhaps we could use a hook script to enforce it on the master 
} > repository.
} 
} Biggest problem is if the change in the mail doesn't exactly match the
} files being patched, in which case there's not identifying information
} in the mail to figure out the commit.  If the person grabbing the patch
} uses "git note" manually, or as a filter to grab X-Seq, then it works.

I'm not sure this is necessary?  We currently rely on people to manually
insert the X-Seq into their commit logs.  Attempting to automatically
extract it from the list archives sounds like a complete nightmare.

Further we sometimes reference X-Seq numbers of messages that don't have
a patch at all, just to connect a change to a background discussion.

Re: Access to CVS

[Phil Pennock]

On 2012-12-05 at 01:40 -0800, Bart Schaefer wrote:
> I'm not sure this is necessary?  We currently rely on people to manually
> insert the X-Seq into their commit logs.  Attempting to automatically
> extract it from the list archives sounds like a complete nightmare.
> 
> Further we sometimes reference X-Seq numbers of messages that don't have
> a patch at all, just to connect a change to a background discussion.

Excellent, less work for migration and I can stop feeling guilty for not
writing it myself.

So, with CVS dying a slow death[*], and a git repo already existing, are
you, Bart, happy with the idea of switching to Git?

Peter?

If so, what's actually needed?  A guideline on the workflow?  Someone
with sourceforge project admin rights to make changes there?  Something
else?

I'm using git enough to be doing horrid nasty things to it.  I'm happy
to try to help out, short term.  I know, that's not the right answer,
but it's all I can commit to.

Anyone?

[*] FreeBSD switching away, code-bases not really maintained, little
    modern tooling continuing to support it, and it's always been just
    frustrating.  Git's frustrating too, but with some hope for the
    future, in my stupid optimistic moments.  Mercurial's nicer to use,
    but doesn't have the momentum that Git does, and zsh already has the
    unofficial git synchronised repo.

Re: Access to CVS

[Frank Terbeck]

Phil Pennock wrote:
[...]
> If so, what's actually needed?  A guideline on the workflow?  Someone
> with sourceforge project admin rights to make changes there?  Something
> else?

I think a git-switch was last discussed in workers/29966 and the
following thread¹. I linked to some interesting documents in there as
well.

I think the most important outstanding issue is to put something useful
into $ZSH_PATCHLEVEL. `git-describe' can produce reasonable values.

The rest is largely related to workflow. I also whined about the fact
that manually keeping a ChangeLog is a pain in the behind, esp. with a
system that actually already uses changeset instead of changes to
individual files. Which means, that you get a change log for free.

I came up with http://ft.bewatermyfriend.org/comp/genchangelog.html, in
case people would like to have a traditional ChangeLog file around in
release tarballs (although, I'd still argue that a release tarball only
needs a list of user-visible changes, as long as the VCS history is
publicly available for everyone to look at).


With regard to the actual switch: Someone could prepare a patch-series
that make the source-tree git-aware ($ZSH_PATCHLEVEL conversion etc) and
make that repository available on bitbucket (or github or whatever) for
review. Once that repository is fine, the changes can be merged in the
sf.net repository and the primary VCS could be switched, by someone with
the appropriate access.


Regards, Frank

¹ http://thread.gmane.org/gmane.comp.shells.zsh.devel/23984/focus=23992

-- 
In protocol design, perfection has been reached not when there is
nothing left to add, but when there is nothing left to take away.
                                                  -- RFC 1925

Re: Access to CVS

[Aaron Schrab]

At 13:11 +0100 05 Dec 2012, Frank Terbeck <ft@bewatermyfriend.org> wrote:
>I think the most important outstanding issue is to put something useful
>into $ZSH_PATCHLEVEL. `git-describe' can produce reasonable values.

The following patch seems to produce decent results.  Such as:

1004$ echo $ZSH_PATCHLEVEL
zsh-5.0.0-91-g2c149d7

Contrary to a previous comment this does give some indication of 
relationships between different patch levels.  The "91" in that string 
is the number of commits since the named tag (zsh-5.0.0) in this case.

--- 8< ---
Subject: [PATCH] Generate patch level using `git describe`

Generate the patch level using `git describe` rather than relying on the
CVS $Revision$.  Need to use the `--tags` option, since currently there
are no annotated tags.

Since changes to the patchlevel could now be caused by changes to any
file, force the rule to be called every time that `make` is run.  But,
only update the file when there are actually changes to prevent
unnecessary rebuilding of other build products (currently just
`params.o` and `zsh`).
---
 Src/zsh.mdd |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Src/zsh.mdd b/Src/zsh.mdd
index 6e90776..5d9460d 100644
--- a/Src/zsh.mdd
+++ b/Src/zsh.mdd
@@ -39,10 +39,10 @@ params.o: patchlevel.h
 version.h: $(sdir_top)/Config/version.mk zshcurses.h zshterm.h
 	echo '#define ZSH_VERSION "'$(VERSION)'"' > $@
 
-patchlevel.h: $(sdir_top)/ChangeLog
-	sed -ne \
-	's/^\* *\$$''Revision: \(.*\) ''\$$/#define ZSH_PATCHLEVEL "\1"/p' \
-	$(sdir_top)/ChangeLog >patchlevel.h
+patchlevel.h: FORCE
+	echo '#define ZSH_PATCHLEVEL "'`git describe --tags`'"' > $@.tmp
+	cmp $@ $@.tmp && rm -f $@.tmp || mv $@.tmp $@
+FORCE:
 
 zshcurses.h: ../config.h
 	@if test x$(ZSH_CURSES_H) != x; then \
-- 
1.7.10.4

Re: Access to CVS

[Aaron Schrab]

At 16:13 -0500 05 Dec 2012, I wrote:
>+	echo '#define ZSH_PATCHLEVEL "'`git describe --tags`'"' > $@.tmp

Thinking about this a bit more, that should probably use the git 
describe's --long option as well.  That way it will consistently produce 
output in the tag-commits-hash format rather than just giving the tag 
when there are no later changes.

Re: Access to CVS

[Peter Stephenson]

On Wed, 5 Dec 2012 06:26:47 -0500
Phil Pennock <zsh-workers+phil.pennock@spodhuis.org> wrote:
> So, with CVS dying a slow death[*], and a git repo already existing, are
> you, Bart, happy with the idea of switching to Git?
> 
> Peter?
> 
> If so, what's actually needed?  A guideline on the workflow?  Someone
> with sourceforge project admin rights to make changes there?  Something
> else?

Apart from sorting out the patch level and the mailing list links, it
really just needs someone to take it on who can keep managing it, or at
least advising on it since it really shouldn't take any special managing
once it's set up.  I don't think there's anything significant in the way.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: Access to CVS

[Peter Stephenson]

On Wed, 5 Dec 2012 19:50:13 +0000
Peter Stephenson <p.w.stephenson@ntlworld.com> wrote:
> Apart from sorting out the patch level and the mailing list links, it
> really just needs someone to take it on who can keep managing it, or at
> least advising on it since it really shouldn't take any special managing
> once it's set up.  I don't think there's anything significant in the way.

By the way, if anyone thinks they do have the time to spend on this, let
me know and I'll make sure they get the appropriate sourceforge
permissions.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: Access to CVS

[Aaron Schrab]

At 19:50 +0000 05 Dec 2012, Peter Stephenson <p.w.stephenson@ntlworld.com> wrote:
>Apart from sorting out the patch level and the mailing list links, it

I'm still unclear about what is expected in regards to handling of the 
mailing list links.  Why is it necessary to handle those differently for 
git than is currently done with CVS, just mention the sequence number in 
the commit message?

For patches that are sent to the mailing list and then added to the 
official repository the sequence number would obviously be known before 
the commit is done, so the commit message could be edited to include it 
at that time.

If submissions start being sent more in the form of pull requests rather 
than patches sent to the list, the changes could be merged using `git 
merge --no-ff --edit` (the --edit option is the default in recent 
versions of git, so wouldn't always be necessary) to create a new commit 
with its own commit message where the sequence number could be included.  
This would mean that somebody who uses `git bisect` to try to determine 
where something was introduced would likely find the original commit, 
and would need to look forward a bit in the history to find the relevant 
sequence number; but that doesn't seem to be a huge burden to me.

This has the advantage that these links would be in the commit message 
no matter if the commit was done before or after the conversion.  Since 
there isn't really a standard format for these messages, it would be 
difficult to automatically convert the existing ones and it would be a 
tedious (and error-prone) process to do that manually.  It also doesn't 
require that people need to know anything about git notes which are 
still somewhat of an obscure area of git.

Re: Access to CVS

[Alex Ogier]

[-- Attachment #1: Type: text/plain, Size: 2187 bytes --]

For pull requests that originate outside of patches, a convenient work flow
is to have the committer merge with 'git merge --squash' as a matter of
course. This way allows all of the advantages of distributed version
control while still keeping mainline history a linear sequence of clean
patches you can bisect to.

Best,
Alex Ogier
On Dec 6, 2012 4:06 PM, "Aaron Schrab" <aaron@schrab.com> wrote:

> At 19:50 +0000 05 Dec 2012, Peter Stephenson <p.w.stephenson@ntlworld.com>
> wrote:
>
>> Apart from sorting out the patch level and the mailing list links, it
>>
>
> I'm still unclear about what is expected in regards to handling of the
> mailing list links.  Why is it necessary to handle those differently for
> git than is currently done with CVS, just mention the sequence number in
> the commit message?
>
> For patches that are sent to the mailing list and then added to the
> official repository the sequence number would obviously be known before the
> commit is done, so the commit message could be edited to include it at that
> time.
>
> If submissions start being sent more in the form of pull requests rather
> than patches sent to the list, the changes could be merged using `git merge
> --no-ff --edit` (the --edit option is the default in recent versions of
> git, so wouldn't always be necessary) to create a new commit with its own
> commit message where the sequence number could be included.  This would
> mean that somebody who uses `git bisect` to try to determine where
> something was introduced would likely find the original commit, and would
> need to look forward a bit in the history to find the relevant sequence
> number; but that doesn't seem to be a huge burden to me.
>
> This has the advantage that these links would be in the commit message no
> matter if the commit was done before or after the conversion.  Since there
> isn't really a standard format for these messages, it would be difficult to
> automatically convert the existing ones and it would be a tedious (and
> error-prone) process to do that manually.  It also doesn't require that
> people need to know anything about git notes which are still somewhat of an
> obscure area of git.
>

Re: Access to CVS

[Frank Terbeck]

Alex Ogier wrote:
> For pull requests that originate outside of patches, a convenient work flow
> is to have the committer merge with 'git merge --squash' as a matter of
> course. This way allows all of the advantages of distributed version
> control while still keeping mainline history a linear sequence of clean
> patches you can bisect to.

Wait a minute, `squash'? Doesn't that mean, that a reduce a series of
perfectly separated patches into one single blob of changes? If you want
to enforce linear history, why not require contributors to rebase their
series on top of the current development?

That being said, I'd still prefer if contributions came in via patches
to the mailing list only.

Regards, Frank

Re: Access to CVS

[Aaron Schrab]

At 02:13 -0500 07 Dec 2012, Alex Ogier <alex.ogier@gmail.com> wrote:
>For pull requests that originate outside of patches, a convenient work flow
>is to have the committer merge with 'git merge --squash' as a matter of
>course. This way allows all of the advantages of distributed version
>control while still keeping mainline history a linear sequence of clean
>patches you can bisect to.

While that would take care of the problem that I mentioned about, 
bisecting to a commit that doesn't mention a mailing list sequence 
number I believe it creates more, worse issues.

With that a change set that involved a number of commits would be 
reduced to a single one, so bisecting to that wouldn't give as much 
information about the actual change which caused the problem.  It also 
loses the finer-grained information about the changes for other 
purposes.

Also, this would not be convenient for the submitter of the pull 
request.  If a normal merge is done, it is easy for the submitter (or 
other people) to determine that the branch was fully merged, since the 
submitted commits are part of the history.  With --squash, if the 
submitter wants to determine if the changes were merged as-is or if 
further modifications were done a more thorough examination would need 
to be done, especially if the merge was done on top of a different 
commit than where the original branch was based.

Re: Access to CVS

[François Revol]

On 07/12/2012 16:11, Aaron Schrab wrote:
> Also, this would not be convenient for the submitter of the pull
> request.  If a normal merge is done, it is easy for the submitter (or
> other people) to determine that the branch was fully merged, since the
> submitted commits are part of the history.  With --squash, if the
> submitter wants to determine if the changes were merged as-is or if
> further modifications were done a more thorough examination would need
> to be done, especially if the merge was done on top of a different
> commit than where the original branch was based.

Well you can merge back master into your branch, then git diff master
will tell if there are still differences...
But it's unhandy.

François.

Re: Access to CVS

[Aaron Schrab]

At 16:37 +0100 07 Dec 2012, François Revol <revol@free.fr> wrote:
>On 07/12/2012 16:11, Aaron Schrab wrote:
>> Also, this would not be convenient for the submitter of the pull
>> request.  If a normal merge is done, it is easy for the submitter (or
>> other people) to determine that the branch was fully merged, since the
>> submitted commits are part of the history.  With --squash, if the
>> submitter wants to determine if the changes were merged as-is or if
>> further modifications were done a more thorough examination would need
>> to be done, especially if the merge was done on top of a different
>> commit than where the original branch was based.
>
>Well you can merge back master into your branch, then git diff master
>will tell if there are still differences...
>But it's unhandy.

I've generally found it more convenient to rebase a copy of the branch 
in question on top of the commit where it was applied by the upstream 
maintainer, then compare my results to what was published by the 
upstream.

Re: Access to CVS

[Frank Terbeck]

Aaron Schrab wrote:
> At 19:50 +0000 05 Dec 2012, Peter Stephenson <p.w.stephenson@ntlworld.com> wrote:
>>Apart from sorting out the patch level and the mailing list links, it
>
> I'm still unclear about what is expected in regards to handling of the mailing
> list links.  Why is it necessary to handle those differently for git than is
> currently done with CVS, just mention the sequence number in the commit
> message?

Obviously, you don't *have* to change anything about that.

However the path of a patch currently looks like this: You hack up the
patch. Then you send it to the mailing list. You wait for the mail to
arrive at the mailing list. Then you pick up the X-Seq: header number
from the mail that returns from the mailing list software. Now you add
an entry to ChangeLog that mentions the X-Seq: number, the files that
were changed in the patch; plus the first line of the actual commit
message. (If you're just the committer and not the author of the patch
you also mention the original author's name.)

That's not very convenient. I don't mind the mail going through the
mailing list. That's good for review and stuff like that. But it would
be pretty neat, if I could save a mail from my MUA somewhere and run
"git am foo.patch" on it. If that would extract the X-Seq: number from
the mail and put it in front of the first line of the commit message,
then that would require no manual intervention at all. (Well, that and
an automatically generated ChangeLog instead of a manually updated one.)

I'd need to take a look at git-am to see whether there is a hook that
would let us do something like that.

Another way would be to put the number into notes. However there would
be potential for that to be forgotten.

> For patches that are sent to the mailing list and then added to the official
> repository the sequence number would obviously be known before the commit is
> done, so the commit message could be edited to include it at that
> time.

Indeed.

> If submissions start being sent more in the form of pull requests rather than
> patches sent to the list [...]

How about not doing that? :)

It's not like it is hard to produce series of a larger number patches
with "git format-patch". And even sending them is trivial with "git
send-email".

That way, the way we handle contributions doesn't change a whole lot.
Everything would still pass the mailing list. Pretty much like git
development itself works. And if it scales for them, it will scale for
us - just judging by the sheer amount of patches they receive.

> This has the advantage that these links would be in the commit message no
> matter if the commit was done before or after the conversion.

ACK. Also, that would mean that both the SHA1 number as well as the
X-Seq: number would be listed in a ChangeLog generated by [1]. :-)

So that would mean that you could quickly do lookups of the individual
change in git history as well as the mailing list archive.

> Since there
> isn't really a standard format for these messages, it would be difficult to
> automatically convert the existing ones and it would be a tedious (and
> error-prone) process to do that manually.  It also doesn't require that people
> need to know anything about git notes which are still somewhat of an obscure
> area of git.

ACK to the obscurity of git-notes. IIRC there were issues with some git
tools and notes to, like they where lost when someone did a rebase? But
maybe that's fixed by now... Still, you have a point.


Regards, Frank

[1] http://ft.bewatermyfriend.org/comp/genchangelog.html

-- 
In protocol design, perfection has been reached not when there is
nothing left to add, but when there is nothing left to take away.
                                                  -- RFC 1925

Re: Access to CVS

[Christian Neukirchen]

Frank Terbeck <ft@bewatermyfriend.org> writes:

> That's not very convenient. I don't mind the mail going through the
> mailing list. That's good for review and stuff like that. But it would
> be pretty neat, if I could save a mail from my MUA somewhere and run
> "git am foo.patch" on it. If that would extract the X-Seq: number from
> the mail and put it in front of the first line of the commit message,
> then that would require no manual intervention at all. (Well, that and
> an automatically generated ChangeLog instead of a manually updated one.)
>
> I'd need to take a look at git-am to see whether there is a hook that
> would let us do something like that.

Just write a tool that takes the mail, extracts X-Seq: and fiddles it
into the Subject.  Then pipe that into git-am.

-- 
Christian Neukirchen  <chneukirchen@gmail.com>  http://chneukirchen.org

Re: Access to CVS

[Frank Terbeck]

Christian Neukirchen wrote:
> Frank Terbeck <ft@bewatermyfriend.org> writes:
>> [...] if I could save a mail from my MUA somewhere and run
>> "git am foo.patch" on it. If that would extract the X-Seq: number from
>> the mail and put it in front of the first line of the commit message,
[...]
>> I'd need to take a look at git-am to see whether there is a hook that
>> would let us do something like that.
>
> Just write a tool that takes the mail, extracts X-Seq: and fiddles it
> into the Subject.  Then pipe that into git-am.

Right, that's a good point. Since we'd have to document how to configure
git-am to respect the X-Seq: header anyway, we could just to that
aswell. And keep the script in Util/git-am or something along those
lines.

Regards, Frank

Re: Access to CVS

[Frank Terbeck]

Frank Terbeck wrote:
> Christian Neukirchen wrote:
[...]
>> Just write a tool that takes the mail, extracts X-Seq: and fiddles it
>> into the Subject.  Then pipe that into git-am.
>
> Right, that's a good point. Since we'd have to document how to configure
> git-am to respect the X-Seq: header anyway, we could just to that
> aswell. And keep the script in Util/git-am or something along those
> lines.


...although. IIRC, you can feed complete mbox files into git-am, which
would make that script a little more complex, albeit not impossible to
get right.

Regards, Frank

Re: Access to CVS

[Bart Schaefer]

On Dec 7, 10:29am, Frank Terbeck wrote:
}
} I'd need to take a look at git-am to see whether there is a hook that
} would let us do something like that.
} 
} Another way would be to put the number into notes. However there would
} be potential for that to be forgotten.

I'm not a git power-user [*] -- is there a push-time hook that could
issue a warning if there's no sequence number in the log message?  Is
there anything like "cvs admin -m" that allows you to update the log
message after the fact?

[*] This (and that neither is PWS) is probably a significant reason why
we're still using CVS for zsh.  I've got my own local CVS repository and
tools for doing the equivalent of "rebase" etc., so I'm rarely doing
work directly against the main repository.

Re: Access to CVS

[Aaron Schrab]

At 07:31 -0800 07 Dec 2012, Bart Schaefer <schaefer@brasslantern.com> wrote:
>I'm not a git power-user [*] -- is there a push-time hook that could
>issue a warning if there's no sequence number in the log message?

Not currently, there's been a little bit of discussion on adding a hook 
that would be called before a push was done, but real progress on that 
last I checked.

>Is there anything like "cvs admin -m" that allows you to update the log
>message after the fact?

There's `git commit --amend` which allows modifying both the commit 
message and contents of the most recent commit.  If you want to modify 
the message on an older commit, you can use `git rebase -i HEAD~10` to 
begin an interactive rebase of the 10 (or some other number) most recent 
commits and choose to "reword" the commit message of any of those, or 
even choose to "edit" any of those commits modifying both the content 
and message.

Either of those options involves rewriting history, so should not be 
done for commits that have already been made public.  (But the rebase 
one won't change history of commits older than what you actually edit or 
reword, so there isn't a huge problem with choosing too big a number 
when beginning).

Re: Access to CVS

[Peter Stephenson]

On Thu, 06 Dec 2012 19:05:22 -0500
Aaron Schrab <aaron@schrab.com> wrote:
> I'm still unclear about what is expected in regards to handling of
> the mailing list links.  Why is it necessary to handle those
> differently for git than is currently done with CVS, just mention the
> sequence number in the commit message?

I'm expecting (from my limited knowledge of git) that git-aware people
will do the following:

- Play with the change locally, committing it, possibly multiple times.
  I don't see any reason you'd *have* to do this, it just strikes me
  as the natural way a developer used to git would work, so you have
  a record in the archive of what went to the list.  The ability to
  do this is one of the big advantages of the distributed system.
- Send the overall diff of the changes to the mailing list.
- If it needs tweaking, there might be further local commits.
- When it looks OK, push the set of changes to the main repository.

So the issue would be to associate the link at the point where it got
pushed.

I don't know enough about git to say if what you or Alex or others are
suggesting fits in with this.

pws

Re: Access to CVS

[Frank Terbeck]

Peter Stephenson wrote:
> Aaron Schrab <aaron@schrab.com> wrote:
>> I'm still unclear about what is expected in regards to handling of
>> the mailing list links.  Why is it necessary to handle those
>> differently for git than is currently done with CVS, just mention the
>> sequence number in the commit message?
>
> I'm expecting (from my limited knowledge of git) that git-aware people
> will do the following:
>
> - Play with the change locally, committing it, possibly multiple times.
>   I don't see any reason you'd *have* to do this, it just strikes me
>   as the natural way a developer used to git would work, so you have
>   a record in the archive of what went to the list.  The ability to
>   do this is one of the big advantages of the distributed system.

Exactly. Potentially, you could refine a set of changes until you're
perfectly happy with it and not pile refinement upon refinement on top
of your original series as small commits.

With git, history only becomes immutable when it's made public (i.e.
pushed to a central server). Because when people base work off of it and
you still change it afterwards, the SHA1 sums will change and that'll
just blow up into the face of anyone who already worked with the old
history.

> - Send the overall diff of the changes to the mailing list.

Yup.

> - If it needs tweaking, there might be further local commits.

Right. That would be one of the refinements I talked about earlier.

> - When it looks OK, push the set of changes to the main repository.

Yes. And git helps with making things easier with external contributors
who don't have commit access (yet). Because git has things like
"git-am". With that you can just save a mail that contains a patch to a
file and feed it into "git am". It'll extract information like "author"
and "commit message" from the mail and commit everything in your local
repository, ready to be pushed.

> So the issue would be to associate the link at the point where it got
> pushed.

It would be great if we could make "git-am" process the X-Seq: header,
too. If that would be possible, integrating someone else's patch from
the mailing list would boil down to this:

  - Save the mail to a file.
  - git am foo.patch
  - git push


Regards, Frank

-- 
In protocol design, perfection has been reached not when there is
nothing left to add, but when there is nothing left to take away.
                                                  -- RFC 1925

Re: Access to CVS

[Simon Ruderich]

[-- Attachment #1.1: Type: text/plain, Size: 1347 bytes --]

On Fri, Dec 07, 2012 at 12:03:31PM +0100, Frank Terbeck wrote:
> It would be great if we could make "git-am" process the X-Seq: header,
> too. If that would be possible, integrating someone else's patch from
> the mailing list would boil down to this:
>
>   - Save the mail to a file.
>   - git am foo.patch
>   - git push

On Thu, Dec 13, 2012 at 03:57:47PM +0100, Simon Ruderich wrote:
> Sadly git-am doesn't provide any hooks which get the original
> patch message as argument.
>
> [snip]

Turns out this isn't quite true.

Attached is a simple applypatch-msg hook which extracts the X-Seq
from the original patch and prepends it to the commit message (if
the message doesn't already contain a sequence number).

The hook should work fine all Git versions and works fine with
multiple patches (mbox of patches or multiple patch files passed
to git am).

To use it simply drop it in .git/hooks/ and chmod +x it. Please
tell me what you think. If it works fine we should ship it in
Etc/ and developers can just symlink it into .git/hooks/.


Btw. what's missing to complete the Git conversion? Please tell
me if there's anything I can do to help. I'd really like to see
Zsh finally switch to Git.

Regards
Simon
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

[-- Attachment #1.2: applypatch-msg --]
[-- Type: text/plain, Size: 722 bytes --]

#!/bin/sh

# applypatch-msg for Zsh which extracts X-Seq from the patch and prepends it
# to the commit message.


if test ! -f "$1"; then
    exit 0
fi

# Path to ".git/rebase-apply/" directory.
dotest=`dirname "$1"`
# Path to the patch file which will be applied.
this=`cat "$dotest/next"`
patch="$dotest/`printf '%04d' "$this"`"

# Extract sequence number.
sequence=`grep -E '^X-Seq: ' "$patch" | awk '{ print $2 }'`
if test -z "$sequence"; then
    exit 0
fi

# Prepend sequence number to commit message if not already present.
if ! grep -E '^unposted: ' "$1" > /dev/null &&
   ! grep -E '^[0-9][0-9]*: ' "$1" > /dev/null; then
    printf "%s: " "$sequence" > "$1.tmp"
    cat "$1" >> "$1.tmp"
    mv "$1.tmp" "$1"
fi

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

Re: Access to CVS

[Simon Ruderich]

[-- Attachment #1: Type: text/plain, Size: 562 bytes --]

On Sun, Mar 17, 2013 at 03:55:07PM +0100, Simon Ruderich wrote:
> Attached is a simple applypatch-msg hook which extracts the X-Seq
> from the original patch and prepends it to the commit message (if
> the message doesn't already contain a sequence number).

Now that we've switched to Git, this applypatch-msg hook should
be useful (if it works). Could you please have a look and test it
when you apply patches. Suggestions are welcome.

Regards
Simon
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Access to CVS

[Oliver Kiddle]

On 7 Dec, Peter Stephenson wrote:
> I'm expecting (from my limited knowledge of git) that git-aware people
> will do the following:
> 
> - Play with the change locally, committing it, possibly multiple times.
>   I don't see any reason you'd *have* to do this, it just strikes me
>   as the natural way a developer used to git would work, so you have
>   a record in the archive of what went to the list.  The ability to
>   do this is one of the big advantages of the distributed system.
> - Send the overall diff of the changes to the mailing list.
> - If it needs tweaking, there might be further local commits.
> - When it looks OK, push the set of changes to the main repository.

But would you want the "set of changes" to appear as several changes or
one single change in the main repository? And if other changes have been
applied since the patches were posted to the mailing list, would you
prefer that checksums are preserved but you have a merge commit?

For a project like zsh which has a small number of developers, I think
it is better to keep things simple and have a linear history (avoiding
merge commits). To produce that overall diff Peter mentions in the
second stage, you would probably use rebase to squash all your
intermediate steps. As with our current cvs practices, big changes that
warrant multiple patches, also warrant multiple mailing list posts. I
would also be happy if later tweaks also get squashed, especially if
we're stuffing X-Seq numbers in commit messages and checksums from a git
am are already invalidated. (The main advantage of git notes is that
checksums are preserved so you can apply a change from the mailing list
and it is handled more cleanly when the patch appears in the main
repository.)

Are people happy enough with the history as it is in the Sourceforge
mirror. Using it as-is has advantages for people that already use it.
I think that to make the switch, we essentially just need to ask Wayne
to turn off his cron job.

Oliver

Re: Access to CVS

[Frank Terbeck]

Oliver Kiddle wrote:
> But would you want the "set of changes" to appear as several changes or
> one single change in the main repository? And if other changes have been
> applied since the patches were posted to the mailing list, would you
> prefer that checksums are preserved but you have a merge commit?
>
> For a project like zsh which has a small number of developers, I think
> it is better to keep things simple and have a linear history (avoiding
> merge commits).

I agree.

> To produce that overall diff Peter mentions in the
> second stage, you would probably use rebase to squash all your
> intermediate steps.

Just to clarify: You don't mean to squash everything to one blob of
changes, if there were logically separated changeset in the commits
before, right?

You mean to use interactive rebasing to get rid of those "Crap, forgot a
semicolon here and there." commits before submitting to the list?

> As with our current cvs practices, big changes that
> warrant multiple patches, also warrant multiple mailing list posts. I
> would also be happy if later tweaks also get squashed, especially if
> we're stuffing X-Seq numbers in commit messages and checksums from a git
> am are already invalidated.

I think git-am would still work if we had something that would scan a
saved mail for the X-Seq: header, amend Subject and then feed that into
git-am.

> (The main advantage of git notes is that
> checksums are preserved so you can apply a change from the mailing list
> and it is handled more cleanly when the patch appears in the main
> repository.)

Sure, but how well are notes supported within git as a whole? Also, who
would we make sure adding notes isn't forgotten?

I think everything, that saves a manual step should be encouraged.

> Are people happy enough with the history as it is in the Sourceforge
> mirror. Using it as-is has advantages for people that already use it.
> I think that to make the switch, we essentially just need to ask Wayne
> to turn off his cron job.

Pretty much, except for re-doing the $ZSH_PATCHLEVEL variable, which
currently is fed the patchlevel from CVS.

Regards, Frank

Re: Access to CVS

[Aaron Schrab]

At 09:23 +0100 12 Dec 2012, Frank Terbeck <ft@bewatermyfriend.org> wrote:
>Pretty much, except for re-doing the $ZSH_PATCHLEVEL variable, which
>currently is fed the patchlevel from CVS.

I sent a patch to change that to be generated using `git describe` in 
#30840, although I did note something that should be slightly modified 
about that in my reply to that message.  I can send an updated version 
if necessary.

Re: Access to CVS

[Oliver Kiddle]

Frank Terbeck wrote:
> 
> Just to clarify: You don't mean to squash everything to one blob of
> changes, if there were logically separated changeset in the commits
> before, right?
> 
> You mean to use interactive rebasing to get rid of those "Crap, forgot a
> semicolon here and there." commits before submitting to the list?

Yes, exactly. If there are logically separated changesets I'd post each in
a separate mailing list message.

> I think git-am would still work if we had something that would scan a
> saved mail for the X-Seq: header, amend Subject and then feed that into
> git-am.

That only really helps when someone who doesn't have permissions to push
to the main repository posts a patch and someone else pushes it on their
behalf. For my own patches, I'd use git commit --amend.

> 
> > (The main advantage of git notes is that
> > checksums are preserved so you can apply a change from the mailing list
> > and it is handled more cleanly when the patch appears in the main
> > repository.)
> 
> Sure, but how well are notes supported within git as a whole? Also, who
> would we make sure adding notes isn't forgotten?

I'm not really arguing for git notes: that point was meant as context
for the preceding sentence.

This discussion has actually convinced me that our best approach is to
amend commit messages for the X-Seq number. Correct me if I'm wrong but
I got the impression that was forming as the general consensus.

It also avoids having to retrospectively add notes for all past commits
in the repository. And it is easy to change to notes at a later point if
we change are minds.

> Pretty much, except for re-doing the $ZSH_PATCHLEVEL variable, which
> currently is fed the patchlevel from CVS.

Aaron's patch looks good for that.

I reckon we're all set to go.

Oliver

Re: Access to CVS

[Bart Schaefer]

On Dec 12,  6:25pm, Oliver Kiddle wrote:
}
} If there are logically separated changesets I'd post each in
} a separate mailing list message.
} 
} > I think git-am would still work if we had something that would scan a
} > saved mail for the X-Seq: header, amend Subject and then feed that into
} > git-am.
} 
} That only really helps when someone who doesn't have permissions to push
} to the main repository posts a patch and someone else pushes it on their
} behalf. For my own patches, I'd use git commit --amend.
} 
} This discussion has actually convinced me that our best approach is to
} amend commit messages for the X-Seq number. Correct me if I'm wrong but
} I got the impression that was forming as the general consensus.
} 
} It also avoids having to retrospectively add notes for all past commits
} in the repository. And it is easy to change to notes at a later point if
} we change are minds.
} 
} I reckon we're all set to go.

I would greatly appreciate it if someone would generate a summary of the
conclusions of this discussion with all the various "recommended" steps
that one would perform, so that it could be added as a sort of how-to in
Etc/zsh-development-guide.

As someone only passingly familiar with git, there are subtleties and
best-practices here that I'm not yet following.

And then for everyone to agree with at least the general outline of that
that summary, before we make the switch -- which I further think should
wait until 5.0.1 has gone out.

Re: Access to CVS

[Oliver Kiddle]

Bart wrote:
> I would greatly appreciate it if someone would generate a summary of the
> conclusions of this discussion with all the various "recommended" steps
> that one would perform, so that it could be added as a sort of how-to in
> Etc/zsh-development-guide.

Ok, how does this look?

The zsh patch archive doesn't exist any more does it?

Having prepared this with git, I realise that "git format-patch" doesn't
really fit with the way we're used to working. It produces full e-mail
headers with the expectation that the commit message forms the actual
body of the e-mail. It also uses [PATCH] instead of PATCH: though that's
minor. As with this message, we often include a patch in a reply. Should
we recommend something else?

> And then for everyone to agree with at least the general outline of that
> that summary, before we make the switch -- which I further think should
> wait until 5.0.1 has gone out.

Yes, waiting for 5.0.1 makes sense.

Oliver

diff --git a/Etc/zsh-development-guide b/Etc/zsh-development-guide
index db78f94..cf7ff1c 100644
--- a/Etc/zsh-development-guide
+++ b/Etc/zsh-development-guide
@@ -32,6 +32,7 @@ Patches
 -------
 
 * Send all patches to the mailing list rather than directly to me.
+  Use a Subject: line starting with "PATCH:".
 
 * Send only context diffs "diff -c oldfile newfile" or unified diffs
   "diff -u oldfile newfile".  They are much easier to read and
@@ -39,7 +40,7 @@ Patches
   intelligently.  Please make sure the filenames in the diff header
   are relative to the top-level directory of the zsh distribution; for
   example, it should say "Src/init.c" rather than "init.c" or
-  "zsh/Src/init.c".
+  "zsh/Src/init.c". Alternatively, use "git format-patch".
 
 * Please put only one bug fix or feature enhancement in a single patch and
   only one patch per mail message.  This helps me to multiplex the many
@@ -52,9 +53,37 @@ Patches
 * Please test your patch and make sure it applies cleanly. It takes
   considerably more time to manually merge a patch into the baseline code.
 
-* There is now a zsh patch archive.  To have your patches appear in the
-  archive, send them to the mailing list with a Subject: line starting
-  with "PATCH:".
+Git Workflow
+------------
+
+* To allow changesets to be cross-referenced between the mailing list
+  archives and version control history, commit messages should start with
+  the mailing list sequence number. This number is generated by the list
+  server and inserted as an X-Seq: header field in the e-mail. To add
+  the number, you can use "git commit --amend" to change the commit.
+
+* Do not merge your private feature branches onto the master branch: a
+  linear history without merge commits is simpler to follow (and to
+  bisect). Both "git cherry-pick" and "git merge --ff-only" can be used
+  bring changes over to another branch without a merge commit.
+
+* It is often useful to regularly check in changes while prototyping a
+  solution on a private branch. When finished, it is better to deliver a
+  clean history. For small changes, use "git merge --squash" to get a
+  single changeset for the feature. Where a change can be logically
+  divided into separate changesets use "git rebase -i master" from the
+  feature branch and squash your many intermediate steps into
+  appropriate changesets that each do something meaningful. Post each
+  changeset separately to the mailing list.
+
+* Before pushing your changes to the main zsh repository, you can use
+  "git pull --rebase" to fetch any new updates from the server and
+  rebase your changes on top of them. You can also use "git rebase
+  master" from your feature branches.
+
+* Patches can be prepared for the mailing list with "git format-patch
+  origin/master". To apply patches from a mailing list message, you can
+  use "git am".
 
 Testing
 -------

Re: Access to CVS

[Simon Ruderich]

[-- Attachment #1: Type: text/plain, Size: 4672 bytes --]

On Thu, Dec 13, 2012 at 01:58:52PM +0100, Oliver Kiddle wrote:
>> I would greatly appreciate it if someone would generate a summary of the
>> conclusions of this discussion with all the various "recommended" steps
>> that one would perform, so that it could be added as a sort of how-to in
>> Etc/zsh-development-guide.
>
> Ok, how does this look?

Looks good to me, see below for some minor comments.

> The zsh patch archive doesn't exist any more does it?
>
> Having prepared this with git, I realise that "git format-patch" doesn't
> really fit with the way we're used to working. It produces full e-mail
> headers with the expectation that the commit message forms the actual
> body of the e-mail. It also uses [PATCH] instead of PATCH: though that's

I've configured mutt's $editor to fix the [PATCH] subject line,
but maybe we could change the policy to allow [PATCH] in the
subject. Last time I checked git format-patch can't create
patches without the [].

> minor. As with this message, we often include a patch in a reply. Should
> we recommend something else?

Those mails (for example this mail) work fine with git am. The
only problems are the mail subject and the body (for the commit
message). The committer could either use git commit --amend or
git am -i to fix the commit message. It's not too much trouble
and just requires adding the X-Seq and fixing the commit message
in your $editor.

Sadly git-am doesn't provide any hooks which get the original
patch message as argument. Therefore we can't extract it
automatically when applying the patch (extending git-am to add
another hook shouldn't be too hard though). Alternatively we
could provide a little wrapper script which is used to apply Zsh
patches and extracts the X-Seq and adapts the subject (I could
write it if you think it's a good idea).

But we could use pre-applyhook to prevent accidental commits
without a X-Seq number in the commit message (checks can be
skipped with commit --no-verify).

We could also use git-am/git-format-patch's scissors feature (man
git-format-patch | less -p '^DISCUSSION'), but I think it just
creates unnecessary burden for the patch sender.

> diff --git a/Etc/zsh-development-guide b/Etc/zsh-development-guide
> index db78f94..cf7ff1c 100644
> --- a/Etc/zsh-development-guide
> +++ b/Etc/zsh-development-guide
> @@ -32,6 +32,7 @@ Patches
>  -------
>
>  * Send all patches to the mailing list rather than directly to me.
> +  Use a Subject: line starting with "PATCH:".

Maybe we should allow [PATCH] as well.

>  * Send only context diffs "diff -c oldfile newfile" or unified diffs
>    "diff -u oldfile newfile".  They are much easier to read and
> @@ -39,7 +40,7 @@ Patches
>    intelligently.  Please make sure the filenames in the diff header
>    are relative to the top-level directory of the zsh distribution; for
>    example, it should say "Src/init.c" rather than "init.c" or
> -  "zsh/Src/init.c".
> +  "zsh/Src/init.c". Alternatively, use "git format-patch".
>
>  * Please put only one bug fix or feature enhancement in a single patch and
>    only one patch per mail message.  This helps me to multiplex the many
> @@ -52,9 +53,37 @@ Patches
>  * Please test your patch and make sure it applies cleanly. It takes
>    considerably more time to manually merge a patch into the baseline code.
>
> -* There is now a zsh patch archive.  To have your patches appear in the
> -  archive, send them to the mailing list with a Subject: line starting
> -  with "PATCH:".
> +Git Workflow
> +------------
> +
> +* To allow changesets to be cross-referenced between the mailing list
> +  archives and version control history, commit messages should start with
> +  the mailing list sequence number. This number is generated by the list
> +  server and inserted as an X-Seq: header field in the e-mail. To add
> +  the number, you can use "git commit --amend" to change the commit.

Maybe we should add:

     before pushing it to zsh's repository.

To make it clear that --amend is only used in the local
repository but not for published commits.

> [snip]
> +
> +* Patches can be prepared for the mailing list with "git format-patch
> +  origin/master". To apply patches from a mailing list message, you can
> +  use "git am".

I think we should add some information for committers how to
"fix" patches sent to the mailing list (e.g. git am -i or git
commit --amend, maybe combined with the custom wrapper which I
mentioned above).

Regards,
Simon
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

Re: Access to CVS

[Bart Schaefer]

On Dec 13,  1:58pm, Oliver Kiddle wrote:
}
} +* Do not merge your private feature branches onto the master branch: a
} +  linear history without merge commits is simpler to follow (and to
} +  bisect). Both "git cherry-pick" and "git merge --ff-only" can be used
} +  bring changes over to another branch without a merge commit.

Is there any way to actually enforce this?  How does one "recover" from
an accidental merge commit?

Re: Access to CVS

[Aaron Schrab]

At 07:37 -0800 13 Dec 2012, Bart Schaefer <schaefer@brasslantern.com> wrote:
>On Dec 13,  1:58pm, Oliver Kiddle wrote:
>}
>} +* Do not merge your private feature branches onto the master branch: a
>} +  linear history without merge commits is simpler to follow (and to
>} +  bisect). Both "git cherry-pick" and "git merge --ff-only" can be used
>} +  bring changes over to another branch without a merge commit.
>
>Is there any way to actually enforce this?

If the main git repository were fully under our control, yes, a hook 
could be setup there to reject pushes which introduce merge commits.  
Unfortunately, I'm not aware of any of the free git hosting sites which 
allow that type of policy to be configured for repositories that they 
host, although I haven't really looked into that.

>How does one "recover" from an accidental merge commit?

If that were to happen, we'd either need to live with it or rewrite 
published history.  I think just allowing it to stay in would be the 
better option, having an occasional merge in the history shouldn't 
introduce much confusion an is better than dealing with the mess of 
altering commits that were already made public.

If the accidental merge is discovered before it has been pushed, or any 
other changes have been made to the target branch the merge can be 
backed out simply by using:

  git reset --hard HEAD~

To reset the branch and working tree to the state before the merge, 
allowing another try at merging the changes without creating a merge 
commit.  This would also blow away any uncommitted changes, although 
those could be safely saved away using `git stash` before doing the 
reset and then recovered later with `git stash pop`.

Re: Access to CVS

[Aaron Schrab]

At 13:58 +0100 13 Dec 2012, Oliver Kiddle <okiddle@yahoo.co.uk> wrote:
>+* Do not merge your private feature branches onto the master branch: a
>+  linear history without merge commits is simpler to follow (and to
>+  bisect). Both "git cherry-pick" and "git merge --ff-only" can be used
>+  bring changes over to another branch without a merge commit.

The `--ff-only` option is only somewhat useful here.  It merely causes 
the merge to be aborted if it can't be done without creating a merge 
commit, in which case some other method of bringing in those changes 
would need to be tried.

Re: Access to CVS

[Peter Stephenson]

On Thu, 13 Dec 2012 13:58:52 +0100
Oliver Kiddle <okiddle@yahoo.co.uk> wrote:
> Bart wrote:
> > I would greatly appreciate it if someone would generate a summary
> > of the conclusions of this discussion with all the various
> > "recommended" steps that one would perform, so that it could be
> > added as a sort of how-to in Etc/zsh-development-guide.
> 
> Ok, how does this look?

Probably OK, although I don't understand all the words.

It might be useful to give a sample list of explicit git commands to use
at each stage, in particular what you'd do for an initial commit, for
updating the commit with the mailing list ID, for any kind of trickery
to reduce the number of commits that get pushed, and for pushing it back
(as this is for those new to git you can assume the relationship between
the local archive and the remote master is simple and let the git gurus
do the clever stuff).

pws

Re: Access to CVS

[Bart Schaefer]

On Dec 13,  4:13pm, Peter Stephenson wrote:
}
} It might be useful to give a sample list of explicit git commands to use
} at each stage, in particular what you'd do for an initial commit, for
} updating the commit with the mailing list ID, for any kind of trickery
} to reduce the number of commits that get pushed, and for pushing it back

Heck, I'd even like an example of the git command for creating a local
feature branch.

Re: Access to CVS

[Phil Pennock]

On 2012-12-13 at 08:20 -0800, Bart Schaefer wrote:
> Heck, I'd even like an example of the git command for creating a local
> feature branch.

You are normally on a branch called "master", which by strong convention
tracks the remote branch "origin/master" (with the tools making it easy
to reconcile).  HEAD is an alias for "tip of the current branch".

% git checkout -b feature_foo
% vi/emacs/ed/flamewar_bait path/to/files ...
% git commit -a                       # or git add, blah blah, git commit

The "checkout -b" basically switches the current working tree state to
be in the new branch named.  "commit -a" is "all".  You can use
"-i <files>" to name explicit files, or use "git add" manually and then
just "git commit".

The workflow described seems to not have code pushed centrally, so
instead when the changes are fixed you can use:
% git rebase -i master
to collapse changes since the branch-point where you split from master.

If you just have the one commit and you want to change the _latest_
commit to add files, then "git commit --amend" works.  This creates a
new commit, with a new id (SHA1 checksum) so the old commit is not
valid.

Thus the caution if you've pushed the changes to where others can see
and pull them, because you can end up requiring others to manually
reconcile "non fast-forward" changes.  Yes, you end up with stale
commits no longer referenced by a branch, and much like a file-system's
lost inodes, these hang around until cleaned up.  You can see them with
"git fsck --unreachable".  Note I've not yet _needed_ to use git-fsck
for anything other than curiosity and learning.  But it's there.

IF you want to make the code available on the server you cloned from as
a branch, and accept that this involves a non-linear history (eg, a
major feature change where it's worth keeping a more accurate history)
then:
  % git push origin feature_foo
  [ do mailing-list stuff here ]

  Switch back to master:
  % git checkout master
  and get the most recent changes:
  % git pull
  then bring in your changes:
  % git merge feature_foo
  % git commit
  % git push

Cleanup:
% git branch -d feature_foo
  % git push origin :feature_foo


It's worth understanding how git does what it does, because a lot of
this is surfaced in the presented abstractions.  The black boxes are
mostly translucent.  Until you learn the underlying layers "git reset"
vs "git checkout" to revert files is confusing as hell.  Or was for me.

git help tutorial
git help tutorial-2
git help gitcore-tutorial

-Phil

Re: Access to CVS

[Frank Terbeck]

Phil Pennock wrote:
[...]
> IF you want to make the code available on the server you cloned from as
> a branch, and accept that this involves a non-linear history (eg, a
> major feature change where it's worth keeping a more accurate history)
> then:

And if you just want do have a local branch, to do your work in and
still want to enforce linear history, you can use the same workflow as
Phil described. You just need to "replay" your changes on top of
"master". "git rebase" does that.

>   % git push origin feature_foo
>   [ do mailing-list stuff here ]
>
>   Switch back to master:
>   % git checkout master
>   and get the most recent changes:
>   % git pull

Switch back to the feature branch:

  % git checkout feature_foo

Rebase the feature branch on top of new changes that were just pulled:

  % git rebase master

This does the following (ASCII graphs from git's manual):

 Commit situation before the rebase:

                  A---B---C topic
                 /
     ...    D---E---F---G master

 And after:

                         A'--B'--C' topic
                        /
     ...    D---E---F---G master

This essentially replays the commits from the topic (or feature) branch
on top of master. That creates commits with different SHA1 sums, hence
the apostrophes with the rebased branch.

>   then bring in your changes:
>   % git merge feature_foo

That merge is a fast-forward then, because it just involves putting the
pointer of the master branch to the tip of the topic branch; because its
linear history again - no real merges involved at all.

>   % git commit
>   % git push
[...]
> git help tutorial
> git help tutorial-2
> git help gitcore-tutorial

Those are actually pretty helpful indeed.

Regards, Frank

-- 
In protocol design, perfection has been reached not when there is
nothing left to add, but when there is nothing left to take away.
                                                  -- RFC 1925

Re: Access to CVS

[Wayne Davison]

[-- Attachment #1: Type: text/plain, Size: 780 bytes --]

On Thu, Dec 13, 2012 at 4:58 AM, Oliver Kiddle <okiddle@yahoo.co.uk> wrote:

> +* Before pushing your changes to the main zsh repository, you can use
> +  "git pull --rebase" to fetch any new updates from the server and
> +  rebase your changes on top of them.


It's nice to create an alias for this to make it less likely that someone
pulls and creates a merge commit.  I like this:

  git config --global alias.up 'pull --rebase --stat'

That lets you just say "git up" to update to the latest code, rebasing any
of your local changes.  It also comments on what files were changed (the
--stat part), which I also like.

Someone might also be interested in my scm helper aliases if you find
yourself changing between several type of scm:  http://opencoder.net/repos/

..wayne..

Re: Access to CVS

[Vin Shelton]

On Tue, Dec 4, 2012 at 5:51 PM, Phil Pennock
<zsh-workers+phil.pennock@spodhuis.org> wrote:
> Perhaps the CVS-on-wire protocol server has issues; can you switch to
> SSH-based access?

I see that ssh access does work; thanks, Phil.

  - Vin