canonical-ubuntu-qa team mailing list archive

[Paride Legovini <paride.legovini@xxxxxxxxxxxxx>]

Hi Ubuntu QA,

In an MP that Tim recently submitted we had a short side discussion
sparked by Brian about adopting some kind of commit style for team
projects [0].

What I propose is a loose version of Conventional Commits for the
"subject" line of commit messages (the very first line):

  https://www.conventionalcommits.org/en/v1.0.0/

The spec requires a commit subject in one of these forms:

  type: description
  type(scope): description

meaning that 'type' is mandatory (types are: fix, feat, build, chore,
ci, docs, style, refactor, perf, test), while 'scope' is optional.
Sample commits:

  ci: add missing yamllint dependency
  chore(service-bundle): update IPs of replaced armhf nodes

I propose a similar approach, but allowing to specify only the scope:

  type: description
  scope: description

Examples:

  ci: add missing yamllint dependency [same as before]
  service-bundle: update IPs of replaced armhf nodes

I personally find this leaves us more flexibility to do what makes
more sense on each case. Moreover I think that, at least in our
projects, the scope is often more interesting than the 'type', but
specifying type(scope) every time is cumbersome.

Deviating from a standard (conventional commits) may seem like a bad
idea, however "strict" conventional commits are mostly useful when
auto-generating changelogs or release notes, which we mostly don't do,
so we'd be getting little benefit from strictly adhering to the
standard. I am very open to discussion on this point.

For the other aspects of commit messages let's just stick with the usual
good practices:

 * Use imperative mood
 * Wrap text to 72 chars
 * Explain the "what" and "why"
 * If a project has a different style, be consistent with that.

git-commit(1) suggests limiting the subject line to 50 chars. I often
find that too restrictive, especially when specifying the commit
type/scope as outlined above. I normally try to stay within 50 chars,
but I believe 72 is fine too even for the subject line.

Let me know what you think!

Paride

[0]
https://code.launchpad.net/~andersson123/autopkgtest-cloud/+git/autopkgtest-cloud-2/+merge/444110