[Python-Dev] Commit changelog: issue number and merges

Victor Stinner victor.stinner at haypocalc.com
Mon May 9 12:32:48 CEST 2011


Commit changelogs are important to understand why the code was changed.
I regulary use hg blame to search which commit introduced a particular
line of code, and I am always happy if I can find an issue number
because it usually contains the whole story.

And since the migration to Mercurial, we have also a great tool adding a
comment to an issue if the changelog contains an issue number (e.g.
changelog starting with "Issue #118888: ..."). So if someone watchs an
issue (is in the nosy list), (s)he will be noticed that a related commit
was pushed. It is not exactly something new: we already do that with
Subversion except that today it is more automatic.

I noticed that some recent commits don't contain the issue number:
please try to always prefix your changelog with the issue number. It is
not "mandatory", but it helps me when I dig the Python history.


For merge commits: many developers just write "merge" or "merge 3.1". I
have to go to the parent commit (and something to the grandparent,
3.1->3.2->3.3) to learn more about the commit.

Would it be possible to repeat the changelog of the original commit in
the merge commits? svnmerge toold prepared a nice changelog containing
the changelog of all pendings commits, even when a commit was "blocked".

For a merge commit, I copy/paste the changelog of the original commit
and I add a "(Merge 3.1) " prefix. I prefer to add explictly a prefix
because it is not easy to notice that it is a merge commit in a
python-checkins email or in the history of hg.python.org.

We need maybe new tools to help the process.


Usecases needing better changelogs:

 - "All changes" section of a buildbot build
 - hg blame (or just hg log)


More information about the Python-Dev mailing list