Conventional Commits
Per the original proposal on the mailing list, we are looking to gather buy-in from platform maintainers on our proposal to adopt the Conventional Commits specification within the TF-A project, enabling us to generate the changelog in future releases.
An investigation period is currently underway, ending 2021-03-31, intended to allow everybody to evaluate additional solutions. At the close of this period, we'll set up a poll here on Phabricator to allow people to vote on their preferred option.
This page has been repurposed after the conclusion of the 2021-02-25 TF-A Tech Forum - please use the mailing list for further discussion.
- Last Author
- CJKay
- Last Edited
- Feb 25 2021, 5:50 PM
Event Timeline
Vote: <Varun Wadekar> (<Tegra>): <disapprove>
Justification: Although I like the proposal in principle, I have some reservation with adding tags to the commit message header. I am concerned that we will lose precious real estate. Plus, it is not clear how to state the sub-module name. For example - "feat(lib/cpus/abc): implement xyz" or "feat(cpus/abc): implement xyz" or "feat(abc): implement xyz".
Question: Is there any interest in adding these tags to the commit message instead of the header? Similar to the "BREAKING CHANGE" tag?
I think this is generally a good move. The transition period will be ugly and unavoidable but we should reap the benefits of it long term. I do agree with Varun's concern about using tags in the headers but it is a trade-off we will have to make for the benefits standard commits offers.
Varun, is the format <conventional commit tag>:<plat> or <submodule>:<short message> not sufficient? I dont think we want to pack too much into the header any way in terms of what the commit is doing.
Yes, I have found that 50 chars is not enough to describe commits many times. Adding a tag would mean sacrificing space. But I am open to adding this tag to the commit message instead of the header. We already plan to add tags to the message anyways?
Hi, I just want to make you aware that the Mbed TLS project has a different, home-rolled solution to this problem:
https://github.com/ARMmbed/mbedtls/blob/development/ChangeLog.d/00README.md
While that lacks the standardization of "Conventional Commits", it allows a different (e.g. shorter) description to be used for the change log compared to the commit message. There may be other pros/cons.
I don't want to get in the way of any decision here but it would be desirable in the long term for all TF projects to be aligned here. Is it worth canvassing the opinion of other projects? If TF-A manages to get Conventional Commits working well, then maybe we can try to get other projects to adopt too.
I think tags in the subject of the commit message are problematic in general. Since commits are expected to capture "logical unit of change", the granularity of tags and commit scope often mismatches. While not mandated in the "Contributors Guide" sections, some commits indeed use tags already (i.e. libc, spmd, docs, etc..). What if a "logical unit of change" affects multiple components (i.e. a fix affects both libc and spmd)?
Perhaps the "type" of tags shall be limited to: "fix", "feat" and "etc" with and optional ! suffix for breaking changes. In addition the "scope" should be banned. This way tags would only capture compatibility information, and a match between commit scope and tags would be enforced. This could also help on "loosing real estate".
Hi, I agree with @danh-arm. We should try to come up with a unified guidance, if possible. I think we will have a better idea of the path forward, once most of the maintainers respond. Personally, I would be open to merging both approaches to get the best of both worlds.
We have had some contact with some other TF.org projects but was not aware of the Mbed TLS project had its own solution already. Its already acknowledged we should to look for a common solution across projects. This discussion is part of that engaging. We do need to make a decision at some point.
Vote: Jens Wiklander (qemu and OP-TEE Dispatcher): disapprove
I too have concerns with adding more tags to the the subject of the commit message.
Adding tags to identify changelog items closer to the end of the commit message seems more attractive. There it wouldn't be much in the way for a human reading the log. I guess that in the commit where we need to add such information it will usually only add another line to the commit.
Another option could be to add the change log data to merge commits instead. It should be safe to assume that the change is well understood when it's merged. However, in the OP-TEE project we're doing a rebase and merge instead of adding merge commits so that wouldn't be an option there.
Hi all, I suggest we move this discussion back to the mailing list so we can track the progression a bit more easily.