0003321: Adopt a 50/72 and one-change-per-commit (merges) style for Mercurial commit messages

Chat on our Discord Server Get the latest version: 3.2.1
Source Code

View Revisions: Issue #3321		[ Back to Issue ]
Summary	0003321: Adopt a 50/72 and one-change-per-commit (merges) style for Mercurial commit messages

Revision	2017-10-30 02:17 by WubTheCaptain
Description	I have found Doomseeker's current Mercurial commit logs difficult to use, due to practice of development/habit. The current structure of a commit message is a freeform text limited by a hyphen (-). This is my personal pet peeve. The full story of changes is not currently told, and an unaware person reverting (undoing) one commit may accidentally create a side effect of reverting another change because multiple related or unrelated changes may appear in one commit. I propose a new format to be adopted: A title 0000002:0000050 characters on first line (title), an empty line, then a message explaining the change (what was changed in detail and why it was necessary) with lines wrapped at 72 characters. A commit should change one important thing. If an implementation (e.g. a new feature) takes multiple sensible changes, instead of one big commit it should be multiple commits and merged with a merge commit. This way, the changes are easier to review, revert individually (an individual commit) or as a whole (reverting the merge commit) and test for bugs. Ideally, this style should be documented in a file such as CONTRIBUTING in version control / source distribution root and enforced.

Revision	2017-10-30 02:19 by WubTheCaptain
Description	I have found Doomseeker's current Mercurial commit logs difficult to use, due to practice of development/habit. The current structure of a commit message is a freeform text limited by a hyphen (-). This is my personal pet peeve. The full story of changes is not currently told, and an unaware person reverting (undoing) one commit may accidentally create a side effect of reverting another change because multiple related or unrelated changes may appear in one commit. I propose a new format to be adopted: A title of max. 50 characters on first line (title), an empty line, then a message explaining the change (what was changed in detail and why it was necessary) with lines wrapped at 72 characters. A commit should change one important thing. If an implementation (e.g. a new feature) takes multiple sensible changes, instead of one big commit it should be multiple commits and merged with a merge commit. This way, the changes are easier to review, revert individually (an individual commit) or as a whole (reverting the merge commit) and test for bugs. Ideally, this style should be documented in a file such as CONTRIBUTING in version control / source distribution root and enforced.

Revision	2017-10-30 02:17 by WubTheCaptain
Steps To Reproduce	$ hg --quiet clone'https://bitbucket.org/Doomseeker/doomseeker/ [^]' $ cd doomseeker/ $ hg log --style compact ... Notice how multiline commits such as 2ee1fde only display the first line as heading. This is no different with default hg log style.

Revision	2017-10-30 02:37 by WubTheCaptain
Steps To Reproduce	$ hg --quiet clone'https://bitbucket.org/Doomseeker/doomseeker/ [^]' $ cd doomseeker/ $ hg --quiet checkout 2123:73b5301c3fc8 $ hg log --style compact ... Notice how multiline commits such as 2ee1fde only display the first line as heading. This is no different with default hg log style.

Revision	2017-10-30 02:40 by WubTheCaptain
Steps To Reproduce	$ hg --quiet clone'https://bitbucket.org/Doomseeker/doomseeker/ [^]' $ cd doomseeker/ $ hg log --style compact 2123:73b5301c3fc8 ... Notice how multiline commits such as 2ee1fde only display the first line as heading. This is no different with default hg log style.

Revision	2017-10-30 02:43 by WubTheCaptain
Steps To Reproduce	$ hg --quiet clone'https://bitbucket.org/Doomseeker/doomseeker/ [^]' $ cd doomseeker/ $ hg log --style compact -r 2121:2ee1fdeb200a ... Notice how multiline commits such as 2ee1fde only display the first line as heading. This is no different with default hg log style.

Revision	2017-10-30 03:03 by WubTheCaptain
Steps To Reproduce	$ hg --quiet clone'https://bitbucket.org/Doomseeker/doomseeker/ [^]' $ cd doomseeker/ $ hg log --patch -r 2121:2ee1fdeb200a ... Notice how multiline commits such as 2ee1fde only display the first line as heading. This is no different with default hg log style.

Questions or other issues? Contact Us.

Links

Doom and Doom II are the property of id Software.