COMMITS.md - A Way to Declare/Detect Conventional Commits

[mentalisttraceur]

Summary

1. Add COMMITS.md file to the root of your repo.

2. The first line of COMMITS.md is a link to the specific Conventional Commits version you are currently using, in the format https://www.conventionalcommits.org/{{language}}/{{version}}.

3. This enables both humans and tools to know if Conventional Commit semantics apply to a commit, and which exact version.

Motivation

Projects, contributors, and tools all benefit from a single convention to communicate that Conventional Commits is in use.

Projects, contributors, tools, and the Conventional Commits specification/community/maintainers all benefit from this convention being future-proof by communicating what version of Conventional Commits is in use.

There is much value in making sure this convention is discoverable, simple, self-explanatory, easy to adopt, hard to accidentally copy incorrectly, open to extension, and doesn't fail in edge cases which are often missed because they only surface after years of growing adoption and usage.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1. A repository using Conventional Commits SHOULD contain a COMMITS.md file in its root directory.

2. If a repository is using Conventional Commits and contains a COMMITS.md file in its root directory, the first line of that file MUST be a UTF-8 string in the form https://www.conventionalcommits.org/{{language}}/{{version}}, where

   • {{version}} is a version string, for example, v1.0.0, which MAY end with a trailing /, and
   • {{language}} is a language identifier.

3. When a repository changes which version of Conventional Commits it is using and contains a COMMITS.md file in its root directory, it MUST update the file to point to the new version.

4. Tools which parse COMMITS.md to learn the Conventional Commits version MUST be able to handle strings both with and without the trailing /.

   For example, both https://www.conventionalcommits.org/en/v1.0.0 and https://www.conventionalcommits.org/en/v1.0.0/ refer to the same version.

5. Tools which parse COMMITS.md to learn the Conventional Commits version MUST ignore the language identifier when determining the version.

   For example, https://www.conventionalcommits.org/en/v1.0.0 and https://www.conventionalcommits.org/pt-br/v1.0.0 both refer to the same version.

   • Such tools MUST be able to handle any valid language identifier, as specified by BCP 47, and tools MAY also tolerate other language identifiers.

     For example, tools MAY use the regular expression (regex) [-a-zA-Z0-9]+ for the language identifier part, or tools MAY parse the whole line as a URL, treating the last path segment as the version.

6. Tools which parse COMMITS.md to learn the Conventional Commits version SHOULD NOT assume that the version from COMMIT.md in one commit applies to any other commit, nor that the versions in COMMITS.md are always increasing, nor that every commit in the history was using Conventional Commits.

   For example, a simple unoptimized tool could inspect the first line from git show <commit>:COMMITS.md for every commit it looks at and pick the interpretation of the commit accordingly; an optimized tool could check for changes to COMMITS.md as it steps through the Git history, similar to how git log COMMITS.md does.

Advantages/Rationale

Both tools and humans can know if Conventional Commit semantics apply to a commit, and which exact version. We can know this with per-commit granularity and it is possible to get that knowledge very efficiently. And we get this per-commit granularity without having to encode the spec version in every commit - you simply make one commit declaring what version you're using now, and this information now carries forward into every future commit until you switch. With that solved, the spec is much more free to evolve, since tools now have a great way to not have their interpretation broken by changes.

By keeping it super simple (the version string and the URL string are one, it's the very first thing in the file by itself on the first line, there is no markdown syntax to parse, etc):

• we make it extremely simple+easy for tools to know what version of the spec is being used,
• it's trivial to see that it's a URL (and the .md extension helps editors/viewers automatically style it as a link, make it clickable, etc), and
• there's a clear single source of truth (as a counter-example, if we follow the temptation to allow wrapping the URL in Markdown syntax, it would be easy to end up with a situation where the display text and the link text both have a version string, but they don't match).

By making the spec explicitly about the first line (so tools just look at the first line and ignore/tolerate the rest), it allows forward-compatibility with future spec changes, extensions, or unforeseen usage adding other information.

Mandating just one encoding reduces the odds that one popular implementation goes looser and all tools end up having to know how to detect or interpret other byte patterns. UTF-8 is the natural choice because it's the overwhelmingly most common encoding in use today, and is fairly good or at least doesn't have any glaring flaws - particularly for the characters in these URLs (all in the ASCII-compatible subset so far, and quite possibly forever).

Tolerating any language identifier in the URL lets projects use the link to their native language - doesn't matter to tools, can really help humans. Since Conventional Commits doesn't seem to have defined any guarantees for the language part of its spec URLs, I assumed the current standard / best practice, but since that's a lot of complexity which we will probably never need, I left the door open for more permissive, accessible (in the standard library of most languages), and far simpler approaches.

Discoverability is really high because it looks like one of the conventional about-this-repo files (all-uppercase, like README, CONTRIBUTING, etc), and it points you right to the full documentation of that commit convention. It would also sort in basically the same place as a CONTRIBUTING file in an alphabetic listing - if I was looking for a "contributing" file and saw a "commits" file (as a dev who already knows what a "commit" is) I'd almost certainly think to look in it.