[PROPOSAL] Adopt standard of commit message "tags" to make reading commit history easier

mike-wendt commented 5 years ago

Challenge

Currently our project has no standardized commit messages and trying to jump in and review/contribute to a PR or issue can be challenging.

Background

NumPy and other projects help to ensure readability of the commit history by using tags in the commit messages to easily identify the actions being taken in each one. The NumPy developer docs highlight their approach for maintaining a large code base with an active community. They have 13 tags that they use to identify the major changes of each commit. In addition, it helps developers more logically group their changes instead of committing tests and documentation changes in one larger commit.

As an example here are the tags they use:

API: an (incompatible) API change
BENCH: changes to the benchmark suite
BLD: change related to building numpy
BUG: bug fix
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
REL: related to releasing numpy

And an example commit message:

ENH: add functionality X to numpy.<submodule>.

The first line of the commit message starts with a capitalized acronym
(options listed below) indicating what type of commit this is.  Then a blank
line, then more text if needed.  Lines shouldn't be longer than 72
characters.  If the commit is related to a ticket, indicate that with
"See #3456", "See ticket 3456", "Closes #3456" or similar.

Proposal

We should adopt a tagging standard that works for the team, either by modifying the NumPy tags, or creating our own tag list for use in all RAPIDS projects (starting with cuDF). In addition to adopting the standard we would provide documentation like NumPy for new contributors about our established practices and enforce them with a githook to check for tags in commit messages.

While we may not need all of the tags above, it may help our project become easier for those in the community to contribute to and get involved as we grow.

mike-wendt commented 5 years ago

FWIW I tend to use a shorter list of tags and drop the : used by NumPy, but I think standardizing this will be better for the whole project.

BLD/TST - change build or tests
DOC - documentation
ENH - enhancement/change
FIX - bug fix (diff from NumPy's BUG)
REV - revert an earlier commit
REL - related to a release

harrism commented 5 years ago

I support this. I'm trying to remember to use this on my commits to try it out.

GregoryKimball commented 2 years ago

Here is the updated location for the Numpy development workflow docs. Here are the latest recommended tags. To close this issue we either need to (1) agree on a tag set and implement pre-commit check or (2) decide to continue without tagging.

API: an (incompatible) API change
BENCH: changes to the benchmark suite
BLD: change related to building numpy
BUG: bug fix
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
REL: related to releasing numpy

GregoryKimball commented 2 years ago

With zero votes in favor and four against, the nays have it. Let the record reflect it.

rapidsai / cudf