Add guidance on commit message content and formatting

[duncandewhurst]

I would find this helpful, as would other helpdesk analysts.

We could add something similar to https://ocp-software-handbook.readthedocs.io/en/latest/git/index.html#commit-messages but with an example to show what type(scope): means in the context of standard development.

[jpmckinney]

For the standard I typically do:

path/to/page: Capitalized, <72 characters, no period

Like

primer/releases_and_records: Use "JSON data" instead of "JSON text"

If the change affects an entire section, you can use e.g. primer: ...

One exception is changelog, which is at history/changelog, but that's too long to type frequently.

Otherwise, the types I use are (most are not expected to be used by others)

• build: Changes to the build system (requirements files, include, script, Makefile, *.cfg, *.py)
• ci: Changes to continuous integration (.github/workflows)
• locale: Changes to translations (docs/locale)
• test: Changes to tests (tests)
• chore: Any other change not warranting a changelog entry (e.g. renaming pages or fixing typographical errors, broken URLs, Markdown syntax, etc.)

[duncandewhurst]

Thanks!

What about for changes to the schema, can we omit the path and just use the name of the schema file?

release-schema: Add `omitWhenMerged` to `publisher`

[jpmckinney]

I think we can do schema for any files under schema/, as it's almost always the release schema anyway.

[duncandewhurst]

Hmm, that might be a bit confusing since the reference documentation is all in a folder named schema so schema could refer either to changes to the entire reference documentation or a change to one of the schema files.

Thinking about it more, is there a preferred approach to combining/splitting up commits, e.g. to add a definition to the schema and an associated entry to schema/reference, should that be separate commits for the schema change and the docs change, or is it sufficient to have a single commit and leave the docs addition implicit?

schema: add `SimpleIdentifier`

[jpmckinney]

It's better to make an ("atomic") change at once, rather than over many commits. That way, reverting a commit doesn't leave the project in an incoherent state.

I'm not sure that the schema ambiguity (which will always be there, unless we do docs(schema), but that's very tedious since most commits are about docs, not other directories) will produce any real confusion. I think it's rather rare for people to read the commit messages of documentation repositories, anyway.

That said, I don't mind using the abbreviated name of the specific schema file e.g. release-schema.

[duncandewhurst]

Okay, makes sense.

Happy for me to author a PR?

[jpmckinney]

That'd be great, thank you :)