feat(ci): add PR title check workflow

[rjan90]

Related Issues

Closes: #12148

Proposed Changes

• A GitHub Actions workflow to automatically check and enforce a consistent format for PR titles
• Started work on CONTRIBUTING.md doc that consolidates contributing expectations in one place. Establish CONTRIBUTING.md #12360

Checklist

Before you mark the PR ready for review, please make sure that:

• Commits have a clear commit message.
• PR title is in the form of of <PR type>: <area>: <change being made>
  • example: fix: mempool: Introduce a cache for valid signatures
  • PR type: fix, feat, build, chore, ci, docs, perf, refactor, revert, style, test
  • area, e.g. api, chain, state, mempool, multisig, networking, paych, proving, sealing, wallet, deps
• Update CHANGELOG.md or signal that this change does not need it.
  • If the PR affects users (e.g., new feature, bug fix, system requirements change), update the CHANGELOG.md and add details to the UNRELEASED section.
  • If the change does not require a CHANGELOG.md entry, do one of the following:
    • Add [skip changelog] to the PR title
    • Add the label skip/changelog to the PR
• New features have usage guidelines and / or documentation updates in
  • Lotus Documentation
  • Discussion Tutorials
• Tests exist for new functionality or change in behavior
• CI is green

[github-actions]

Please update the PR title to match the required format: <type>: <scope>: <subject>

Types: feat, fix, docs, style, refactor, test, chore
Scope: required
Subject: start with lowercase

PR title now matches the required format.

[github-actions]

Please update the PR title to match the required format: <type>: <scope>: <subject>

Types: feat, fix, docs, style, refactor, test, chore
Scope: required
Subject: start with lowercase

[rjan90]

Create a PR with an invalid title format and verify that it's blocked

Confirm that creating a PR with a invalid title format is being requested for change by the GA bot, as per this comment.

PR title now matches the required format.

[rjan90]

Edit a PR title from invalid to valid format and confirm the check passes
Confirm that "Changes requested" gets removed once updated to the correct format.

After updating my title to valid format, I can confirm that the check passes, and also that the "Changes requested" by the bot gets dismissed:

[github-actions]

Please update the PR title to match the required format: <type>: <area>: <subject>

Types: fix, feat, build, chore, ci, docs, perf, refactor, revert, style, test, chore
Area: e.g. api, chain, state, mempool, multisig, networking, paych, proving, sealing, wallet, deps
Subject: start with lowercase

PR title now matches the required format.

[BigLep]

A few thoughts:

1. (raised inline) Any reason we're not just following https://www.conventionalcommits.org/en/v1.0.0/ style?
2. Do we expect to want to roll this out to other FilOz-maintained repos? I assume IPDX has ideas on how this could be done (asked here).
3. What are the thoughts on using a 3rd party action? I realize there's not a lot of code here so it's not a big gain, but others have solved this problem. Examples:
   • https:/marketplace/actions/pr-title-checker
   • https:/marketplace/actions/pr-title-verify
   • https:/Slashgear/action-check-pr-title
     My impetus for raising this is the value for keeping it concise probably goes up if we do want to copy this across multiple repos.

[rvagg]

fwiw I prefer conventional commit style and use it everywhere else, this is the repo that stands out as different in the world of repos I contribute to; but change can be hard for people that have got used to it

One option is to do both for a while and have a migration period.

^(feat|fix|build|chore|ci|docs|perf|refactor|revert|style|test)(\(\w+\))?:\s\w+:\s[a-z].+|^(feat|fix|build|chore|ci|docs|perf|refactor|revert|style|test)(\(\w+\))?:\s[a-z].+

[BigLep]

migration period idea

Seems good/reasonable to me. We could still update our PR template text to steer at the conventional commit style.

Also, I'm realizing we'll need to update the regex to account for [skip changelog]

[rjan90]

1. I agree that moving to the conventional commit style is preferred, and we should have a migration period where both styles are acceptable.

2. I think it would be beneficial to roll this out to the repositories with higher activity and importance (builtin-actors, filecoin-ffi, ref-fvm, go-state-types, go-f3). For many of the smaller repositories with infrequent or less activity, I'm not sure if the benefits of such a title check outweigh the additional work (and potentially cost). However, I'm open-minded if there is an easy way to roll this out to all repositories maintained by FilOz.

3. I will look into those 3rd party actions. Perhaps we can switch to one of these after we have completed the migration period here in the Lotus repo.

I will adjust the PR accordignly

[rjan90]

In 2cf80e7, I have changed:

• Allow optional "[skip changelog]" prefix
• Support both <type>: <scope>: <subject> and <type>(<scope>): <subject> formats
• Use conventional commit <scope> instead of <area>
• Alphabetized the Types and Scope in the body.

[rjan90]

While we are discussing conventions, referring to: Conventional Commits.

The commit contains the following structural elements, to communicate intent to the consumers of your library:
.............
3. BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.

While this convention is primarily for commits (which Rod also has advocated for following: #12238 (comment)), it would be valuable to extend it to PR titles as well, particularly as we default to "squash and merge". By appending a ! after the in the PR title, we can clearly signal that the change is breaking.

[github-actions]

Please update the PR title to match one of the required formats:

1. <type>: <scope>: <subject>
2. <type>(<scope>): <subject>

Types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
Area/Scope: api, chain, state, mempool, multisig, networking, paych, proving, sealing, wallet, deps
Subject: start with lowercase

Optionally, you can add "[skip changelog]" at the start of the title if the change does not require a CHANGELOG.md entry.

[github-actions]

Please update the PR title to match one of the required formats:

1. <type>: <scope>: <subject>
2. <type>(<scope>): <subject>

Types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
Area/Scope: api, chain, state, mempool, multisig, networking, paych, proving, sealing, wallet, deps
Subject: start with lowercase

Optionally, you can add "[skip changelog]" at the start of the title if the change does not require a CHANGELOG.md entry.

[github-actions]

Please update the PR title to match one of the required formats:

1. <type>: <scope>: <subject>
2. <type>(<scope>): <subject>

Types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
Area/Scope: api, chain, state, mempool, multisig, networking, paych, proving, sealing, wallet, deps
Subject: start with lowercase

Optionally, you can add "[skip changelog]" at the start of the title if the change does not require a CHANGELOG.md entry.

PR title now matches the required format.

[github-actions]

Please update the PR title to match one of the required formats:

1. <type>: <scope>: <subject>
2. <type>(<scope>): <subject>

Types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
Area/Scope: api, chain, state, mempool, multisig, networking, paych, proving, sealing, wallet, deps
Subject: start with lowercase

Optionally, you can add "[skip changelog]" at the start of the title if the change does not require a CHANGELOG.md entry.

PR title now matches the required format.

This is a stale review.

[BigLep]

I'm good with this getting merged once feedback incorporated.

I created another PR on top of your PR that starts extracting out some of these contributing conventions as part of #12360

PR title now matches the required format.

[BigLep]

For the record, concerning using off-the-shelf tools given we have had to iterate on this a couple times (e.g., PR #12373) , I did a little more researching. I don't think they'll give us fully what we want and we should finish fine-tuning what we started here:

Tool	Has regex support?	Post customizable comment message?	Supports forks (pull_request_target)?
https:/marketplace/actions/pr-title-checker	Yes	Doesn't comment. It applies a label. No way for us to get a message that links to our conventions.	(Didn't look)
https:/marketplace/actions/pr-title-verify	Yes	Not sure. Not documented.	Not sure. Not documented.
https:/Slashgear/action-check-pr-title	Yes	Yes	No