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. _______________________________________________ Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/archive%40jab.org Security Policy: http://wiki.list.org/x/QIA9