Add example of commit message to contribution guidelines

[hobofan]

As @dirvine pointed out (#47 (comment)) an example of a proper commit message would be helpful in the contribution guidelines, since currently it is only explained in an abstract way.

[jonhoo]

Perhaps also include an issue template?

[hobofan]

I haven't really investigated/used issue/PR templates yet. I am not sure if they really help much.

The main problem we have is people not using the commit message format, adding one feedback roundtrip for PRs. Maybe an PR template that gives a short example of the commit format and points to the CONTRIBUTION.md might help (but by the point of reading it you usually already have written the commit message and then have to go back and amend it 😕).

As for a issue template that proposes a rigid feedback form I am mostly against it. I think that at least for the current stage of the project it hinders more loose feedback which we really want and appreciate. We also don't have a huge ton of issues flowing in yet, so I think this something that should be discussed once(/if) we approach a 2-300 open issues.

[dirvine]

I really support the documentation effort in this library. I suspect if high five is up and running then it can also act as a reminder of good commit messages with an example. I think making clear what the modules or files are after the <style>/ etc. are will help a lot. Many changes will be multi file and maybe the module or target is not so obvious then. A list of the targets may help in that case?

[hobofan]

As of now what comes after <style>/ is only roughly defined as scope. The scope mostly helps when automatically generating a CHANGELOG, as it already provides a rough structure of which changes to group together. In the end the CHANGELOG will always require a bit of manual editing and regrouping so having a more rigid approach will only marginally improve it.

I personally prefer the bit of freedom that is left with the scope (which should be documented if kept), but I can also see the upside for a more fixed form.
Another problem I see with a list of target scopes is that it would have to be kept up-to-date with the structure of the code which I doubt is feasible.

Overall I mostly lean towards keeping it the current semi-freeform, but also adding examples for that to the contribution guide (and a possible PR template).

[dirvine]

👍 Agree

[MichaelHirn]

I added two examples for a complete commit message and how you would create them on the command line when git commiting. In order to close this issue, I would wait if wrong formatted commit messages are still an issue with future PRs, if so we might look into issue templates and other mechanisms for raising awareness about the commit message format.

[dirvine]

Looks good. Also good scope is light, it may make changelogs a bit harder to read, bit I think in the end it is the most effective way forward. I would like to see more projects do this actually. Great to set an example though 👍