Commit message conventions

[big-r81]

Hi,

I'm updating the CONTRIBUTING.md file and there is a broken link to some CouchDB "commit message conventions".

If the commit messages follow [our conventions](@commit-message-conventions)

Are there any written and accessible conventions, that we can link to?

Cheers,
Ronny

[nickva]

I thought it was a link to the old wiki some but couldn't find it. Perhaps it was deleted at some point.

Having looked at some examples online:

• https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53
• https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/

I think something smaller and simpler (less rules) would work best.

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

If you use an issue tracker, add a reference(s) to them at the bottom,
like so:

Resolves: #123

[kocolosk]

LGTM except for maybe the "Resolves X" bit. These days I think of that as a property of the PR rather than the commit. I don't mind getting back in the habit of adding those, but haven't seen it as a common practice lately.

[nickva]

Thanks, @kocolosk. Yeah that makes sense

Perhaps we can phrase it as an option "may reference or auto-resolve an issue" .

GH suggests any of these as a way to reference/auto-close issues:

EDIT: Let's skip the references and auto-closes

[nickva]

Updated version

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

EDIT: removed the issue reference and auto-close keywords

[kocolosk]

The GitHub docs you linked to reinforce the point that they see the relationship between Issues and Pull Requests rather than Issues and commits. We'd also run into friction with long-lived branches like 3.x that are not the default branch:

You can also use closing keywords in a commit message. The issue will be closed when you merge the commit into the default branch, but the pull request that contains the commit will not be listed as a linked pull request.

[nickva]

Hmm good point about the 3.x and main branches. We've seen a few of those cases already. Let's take that out then

[kocolosk]

SGTM to remove that guidance, but I just stopped over here again to note that adding the auto-close in the PR is also limited to the default branch:

When you merge a linked pull request into the default branch of a repository, its linked issue is automatically closed.

#3885 and #3886 are a perfect example where you had the auto-close language in both the commit message and the PR, and yet #3885 is still open :)