[Mailman-Developers] Getting "approval" to go ahead

[Stephen J. Turnbull]

Barry Warsaw writes:

 > Keep feature and bug branches small if possible, and concise, such
 > that they only implement the feature your working on or fix the
 > reported bug.  A little bit of extraneous stuff might be okay if it
 > improves readability, but don't go overboard.

I'd like to gloss this a bit.

(1) Suppose you change a small function whose formatting is not PEP 8
    conformant (or otherwise so ugly you can't help fixing it -- of
    course, check "blame" first, if Barry committed those lines, have
    your eyes checked instead :-).  I would (1) fix the problem in the
    current style, commit, and then (2) reformat the function to PEP
    8, and give that a separate commit.  If the number of lines that
    would *not* be in the diff at all if you didn't mess with style is
    greater than the number of lines in the diff from step (1), don't
    do step (2) without checking with the project leads.

(2) Documentation and test changes implied by your code changes should
    go in the same branch.  In other projects I usually commit docstring
    changes with the code change, and use two more commits, one for
    standalone docs and one for unit tests.

(3) Unrelated documentation changes (eg, a typo you notice in another
    function's docstring, or you want to add a docstring to an
    undocumented function that you had to study) should go in a
    separate *branch*.  I usually have a branch just to collect these
    small improvements, and push them (or submit a merge request,
    depending on the project workflow) all at once.

These practices are noticably tedious for the committer, but I find
they greatly improve the usefulness of commit logs and the readability
of diffs.  It's not officially in the Zen of Python, but widely
acknowledged, that Python should be written with the assumption that
the code will be read many thousand times more often than it's written.