Hi Chris,

 

Thanks for sharing the ppt – it helps with the background and the motivation for the change.

 

Having said that, how do you plan to ask for reviews and track the sign offs? Considering we have a limited audience (maintainers and platform owners) a targeted email to all of them might help (?). This email does not have a “go live” date attached, so people might not understand the importance or action item.

 

Cheers.

 

From: Chris Kay <Chris.Kay@arm.com>
Sent: Friday, February 19, 2021 4:23 AM
To: Varun Wadekar <vwadekar@nvidia.com>
Cc: tf-a@lists.trustedfirmware.org
Subject: RE: Adoption of Conventional Commits

 

External email: Use caution opening links or attachments

 

Hi Varun,

 

Thanks for that. I’ve created a Wiki page to give platform maintainers the opportunity to either sign off or voice their dissent. Additionally, I’ve attached the original presentation (to the page, not the email) given internally on this prior to making these proposals public, in the hope that it provides additional context for why we feel a change like this is necessary.

 

Regards,

Chris

 

From: Varun Wadekar <vwadekar@nvidia.com>
Sent: 18 February 2021 02:01
To: Chris Kay <Chris.Kay@arm.com>
Cc: tf-a@lists.trustedfirmware.org
Subject: RE: Adoption of Conventional Commits

 

Hi Chris,

 

My comments.

 

>> We could, however, mitigate this concern by downgrading subject length errors to warnings, which would give us some flexibility here.

 

I think this is a good compromise.

 

>> I'm open to suggestions on how we can deal with this efficiently.

 

I suggest we start a wiki page and ask all the maintainers and platform owners to sign off. I understand that everyone inside Arm is already aligned, but this will allow others to vote on the proposal. I would like us to vote before you start pushing changes with the new scheme to avoid a cleanup later.

 

>> My view at present is that the biggest benefit comes from standardising how platform maintainers report their changes

 

This means we should try to get a buy in from all maintainers and platform owners before deploying the proposal.

 

>> The alternative is that we ask maintainers to update the changelog themselves

 

We should ask maintainers to vote on this proposal too.

 

I think the best approach is to get a vote from maintainers within a finite time span (2 weeks?) - wiki page is better than email.

 

-Varun

 

From: Chris Kay <Chris.Kay@arm.com>
Sent: Wednesday, February 17, 2021 4:07 PM
To: Varun Wadekar <vwadekar@nvidia.com>
Cc: tf-a@lists.trustedfirmware.org
Subject: Re: Adoption of Conventional Commits

 

External email: Use caution opening links or attachments

 

Hi Varun,

 

Thanks for your feedback!

 

  1. Introducing additional tags will eat into precious real estate. This will be a problem for some changes and developers.
    1. Sorry, you'll have to clarify for me: do you mean tags as in the commit message types/scopes (e.g. feat(xyz): ...)? If so, most commit messages already include this information in one form or another, so I'm not expecting us to start struggling to summarise commits; in most cases we are rewording rather than adding anything new. We could, however, mitigate this concern by downgrading subject length errors to warnings, which would give us some flexibility here.
  1. In the transition period, the proposal has the potential to “pollute” the history
    1. ​I'm afraid I don't have a good answer to this - the alternative is forcing everybody to begin adoption on day one. With that said, we have already begun upstreaming v2.5 contributions that do not follow this scheme, so there is already going to be some level of pollution. I'm open to suggestions on how we can deal with this efficiently.
  1. The proposal will add more work for patches cherry-picked from other projects e.g. libfdt
    1. I'm afraid so. Still, it is work that needs to be done at some point anyway: presently, it's done by a changelog maintainer at each release, so I would argue this just moves the responsibility of the documentation to the contributor rather than relying on a (potentially unreliable) interpretation later.
  1. How do we handle scenarios where platforms donot want to switch to this policy?
    1. My view at present is that the biggest benefit comes from standardising how platform maintainers report their changes, so it is a "we really need this" situation - of the 896 commits that went into the v2.4 release, 461 (51%) of them made changes in the plat directory. Ambiguous commits to areas of the codebase that are not maintained by Arm employees are the biggest pain point, because we cannot realistically reach out to the various maintainers and ask for clarification like we can do internally, so the most we can do is make a best-guess effort when updating the changelog. The alternative is that we ask maintainers to update the changelog themselves, but I suspect we might encounter some friction there!

 

Hope that clarifies.

 

Regards,

Chris

From: Varun Wadekar <vwadekar@nvidia.com>
Sent: 17 February 2021 23:21
To: Chris Kay <Chris.Kay@arm.com>
Cc: tf-a@lists.trustedfirmware.org <tf-a@lists.trustedfirmware.org>
Subject: RE: Adoption of Conventional Commits

 

Hi Chris,

 

This seems like a good proposal to alleviate some of the pain around releases.

 

Some observations/questions.

 

  1. Introducing additional tags will eat into precious real estate. This will be a problem for some changes and developers.
  2. In the transition period, the proposal has the potential to “pollute” the history
  3. The proposal will add more work for patches cherry-picked from other projects e.g. libfdt
  4. How do we handle scenarios where platforms donot want to switch to this policy?

 

I can see how #1 might be of concern to many, but we will have to implement some policy to see how many commits really fall in this category.

 

-Varun

 

From: TF-A <tf-a-bounces@lists.trustedfirmware.org> On Behalf Of Chris Kay via TF-A
Sent: Thursday, February 11, 2021 5:59 AM
To: tf-a@lists.trustedfirmware.org
Subject: [TF-A] Adoption of Conventional Commits

 

External email: Use caution opening links or attachments

 

Hi all,

 

Recently we had an internal discussion on the merits of introducing semantics to commit messages pushed to the main TF-A repository, the conclusion being that we would look to adopting the Conventional Commits specification in the near future. There was one major reason for this, which was to help us in automating the changelog in future releases, but it might also help us to dramatically reduce the overall amount of work needed to make a formal release in the future.

 

This requires some buy-in (or buy-out, in this case) from maintainers because - even though it’s to only a relatively minor extent - it does involve an adjustment to everybody’s workflow. Notably, commit messages will be expected to adopt the structure defined by the specification, which will be enforced by the CI. Most commits that go upstream today adhere to “something that looks like Conventional Commits”, so the change is not exactly sweeping, but any change has the potential be an inconvenience.

 

With that in mind, I propose the following:

  • We collectively adopt the specification, enforced only for @arm.com contributors until such a time that the majority of maintainers are familiar with the new demands
  • We suggest - in the prerequisites documentation - the installation of two helper tools:

 

Installation of these tools will be optional, but I believe they can help with the transition. In the patches currently in review, they are installed as Git hooks automatically upon execution of npm install, so it requires no manual installation or configuration (other than a relatively up-to-date Node.js installation).

 

You’ll find the patches here, and specifically the changes to the prerequisites documentation here. Feel free to review these changes if you have comments specifically on their implementation.

 

Let me know if you have any questions or concerns. If everybody’s on board, we can look to have this upstreamed shortly.

 

Chris