[IPython-dev] Fwd: Last checks on release notes for 0.10

[Fernando Perez]

I was cleaning my inbox and just noticed I'd sent this off-list when
it was meant for the list.  It's basically a wrapup of the 0.10
release notes process with some thoughts on the logs/changes.txt.
Nothing major, I just want it archived on-list, since it was meant to
go there.

---------- Forwarded message ----------
From: Fernando Perez <fperez.net at gmail.com>
Date: Tue, Aug 4, 2009 at 12:11 PM
Subject: Re: [IPython-dev] Last checks on release notes for 0.10
To: Brian Granger <ellisonbg.net at gmail.com>


On Tue, Aug 4, 2009 at 11:07 AM, Brian Granger<ellisonbg.net at gmail.com> wrote:
> Fantastic, that was a huge task for you to write the changes for all of our
> commits for the last year!
>
> We definitely need to come up with a good way of making sure that we all
> write our own changes.

I have to say, it actually wasn't too bad, though it was time
consuming.  But I thought it was going to be worse.  A few comments:

- Both you and Ville had been pretty good about adding your edits to
changes.txt, especially earlier.  There wasn't that much that I had to
re-edit from the changelog.

- When big merges are done, the practice of putting a summary commit
message in the merge is *extremely* useful.  It makes this kind of job
much nicer, because that summary log message can be almost copy/pasted
without changes, if it was well written, rather than dissecting the
next-level messages from the individual commits.

- It's important that we remember to always credit who gave us
something if it's not the committer.  There was a lot of that
information in the commits, so it seems we're doing pretty good on
that front, but obviously I can't know if we missed someone (unless
they tell us). This is just a reminder to keep things up on that
front.  As a reminder, if you are ever committing something that's
completely (or almost so) a third-party contribution, do the commit as

bzr commit --author="Someone Else"

This way it will show that name separately in the log, which makes it
even easier to spot.  Obviously we often rework third party
contributions extensively, but this is still good to keep in mind for
cases when we don't touch the code too much.

- Overall, I just used

bzr log | less

and I was in the end quite happy that it's pretty good and painless.
The individual messages have all the relevant info, if --author is
used it's clear when they are third-party contributions, and the
indentation makes it very easy to read.

For all my unhappiness with bzr's slowness and its braindead behavior
when X11 connections aren't being tunneled, I have to say that for all
the recent flurry of work we've done here it has behaved very very
well.  And I also think that we're reaching a good workflow with the
tool.  Not perfect, but very decent.  Which reminds me of this post by
Linus:

http://torvalds-family.blogspot.com/2009/06/happiness-is-warm-scm.html

Distributed version control is both a tool and a way of working, and I
think many of us (at least I did) at the beginning failed to grasp how
much more of a workflow planning it requires.  The fact that bzr's
docs are woefully short on the workflow details didn't help.  But it's
interesting to see that the Linux kernel crowd, arguably one of the
most technically savvy development communities in the world, even with
having a tailor-made DVCS they created themselves, still needed
several years to find their 'happy spot' in terms of the integration
between the tools and the team's workflow.


In any case, I think I am going to add some of these notes I just
typed up here to our dev documents, and then I'll get on with cutting
out the release.

Stop me now if you think it's a bad idea :)

Cheers,

f