Mention commit messages in the contribution guidelines.

[mkcor]

Description

@stefanv as per the recent email thread about commit messages.

I wasn't 100% sure about linking to the reference @alexdesiqueira and you shared, at least in writing (I think it's okay to hear misnomers, but less okay to read them): In the first paragraph, I suspect that "Well-structured and well-written git commits" stands for "Well-structured git commits and well-written git commit messages" and, slightly later, I wonder whether "writing quality git commits" would stand for "writing quality git commit messages."

Actually, I don't think "writing commits" would be incorrect (that would be writing everything the commit consists of, not only its message). Since this talk by Rose Judge deals with commits overall (not just commit messages---which is also the whole point of the talk), it's not 100% clear to me whether "writing quality git commits" is just short for "writing quality git commit messages."

Anyhow, I went reductionist and decided to link to the good ol' post by Chris Beams on just writing commit messages (which inevitably impacts how you structure actual commits anyway). But I'm happy to update the PR if the majority prefers the other reference.

I removed the part about merge messages since we now 'squash and merge.'

Checklist

• Docstrings for all functions
• Gallery example in ./doc/examples (new features only)
• Benchmark in ./benchmarks, if your changes aren't covered by an
  existing benchmark
• Unit tests
• Clean style in the spirit of PEP8

For reviewers

• Check that the PR title is short, concise, and will make sense 1 year
  later.
• Check that new functions are imported in corresponding __init__.py.
• Check that new features, API changes, and deprecations are mentioned in
  doc/release/release_dev.rst.

[stefanv]

Thank you, Marianne. I think Chris's post is great. Unfortunately, it's also a bit of a slog to get through. I like this summary from Charl Botha's software development guide: https://vxlabs.com/software-development-handbook/#good-commit-messages

Perhaps we should include a similar summary, or link to his?

I am worried that this tiny sentence will get lost in the guidelines. Perhaps we should also update our pull request template to emphasize it?

[mkcor]

All very good points, @stefanv. This summary from Charl Botha's software development guide is great and very fitting, indeed. And it starts with a link to Chris's post, so I've happily made the change.

[grlee77]

Thanks @mkcor

We may also want to mention somewhere in the maintainer guide about editing the messages a bit when squashing the commits. I often delete or condense a number of the less informative ones like "pep8 fix", "apply review comments", etc, while making sure to maintain any Co-authored-by entries.

[mkcor]

@grlee77 good point! Done 13e5ae5.

[stefanv]

Small tweak, since I don't think most people know what "standard" commit messages are. Otherwise I think this is good to go!

[mkcor]

Thanks, @stefanv! Your latest review allowed me to catch a leftover typo (c74c3bf).

[stefanv]

I did a half-baked review yesterday. Apologies for the churn, @mkcor!

[stefanv]

Looks good to me; thanks @mkcor!

[mkcor]

Looks good to me; thanks @mkcor!

@stefanv great! Please go ahead and merge 😅