[Python-Dev] PEP 385: Formatting of Hg checkin notifications

[Nick Coghlan]

Following the python-checkins list, I get to see both the current SVN
notifications and the Hg notifications from Tarek's pushes into the
distutils repository. I realised today that there is one key reason as
to why the latter strikes me as a big wall of unintelligible text,
while I find the SVN notification quite easy to read: vertical
whitespace.

The SVN notification uses vertical whitespace to separate out the log
message and the list of files affected clearly from the rest of the
header fields. It makes it *really* easy to see at a glance what the
checkin was about and which files were affected. For the Hg
notification, both of these fields are embedded in a big header block
along with all the other fields, so it is quite difficult to make out
the same information.

It would be really nice if the formatting could be improved for the
email notifications on the Hg side when we adopt it for the main
CPython repository. The changes would be to:
- add a blank line before and after the summary field
- add a carriage return between the header and content for the summary
field and the files field
- indent the list of files by two spaces and use a carriage return
rather than a comma to separate named files

I've included an example below based on one of Tarek's recent pushes:

Current Hg notification header and start of first diff:
================================================
tarek.ziade pushed 7ebf14ab2840 to distutils2:

http://hg.python.org/distutils2/rev/7ebf14ab2840
changeset:   816:7ebf14ab2840
tag:         tip
user:        Tarek Ziade <tarek at ziade.org>
date:        Sat Nov 13 12:40:33 2010 +0100
summary:     compiler_type -> name
files:       distutils2/compiler/__init__.py,
distutils2/compiler/bcppcompiler.py, distutils2/compiler/ccompiler.py,
distutils2/compiler/cygwinccompiler.py,
distutils2/compiler/msvc9compiler.py,
distutils2/compiler/msvccompiler.py,
distutils2/compiler/unixccompiler.py, distutils2/tests/test_config.py

diff --git a/distutils2/compiler/__init__.py b/distutils2/compiler/__init__.py
--- a/distutils2/compiler/__init__.py
+++ b/distutils2/compiler/__init__.py
@@ -13,7 +13,7 @@
====================================================

Proposed change to separate out summary and files fields:
================================================
tarek.ziade pushed 7ebf14ab2840 to distutils2:

http://hg.python.org/distutils2/rev/7ebf14ab2840
changeset:   816:7ebf14ab2840
tag:         tip
user:        Tarek Ziade <tarek at ziade.org>
date:        Sat Nov 13 12:40:33 2010 +0100

summary:
compiler_type -> name

files:
  distutils2/compiler/__init__.py
  distutils2/compiler/bcppcompiler.py
  distutils2/compiler/ccompiler.py
  distutils2/compiler/cygwinccompiler.py
  distutils2/compiler/msvc9compiler.py
  distutils2/compiler/msvccompiler.py
  distutils2/compiler/unixccompiler.py
  distutils2/tests/test_config.py

diff --git a/distutils2/compiler/__init__.py b/distutils2/compiler/__init__.py
--- a/distutils2/compiler/__init__.py
+++ b/distutils2/compiler/__init__.py
@@ -13,7 +13,7 @@
====================================================

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia