docs: seed CONTRIBUTING.md pr title and changelog expectations

This starts on #12360 as part of landing #12340

.github/pull_request_template.md

@@ -12,15 +12,8 @@
 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 `<type> (<scope>): <subject>`
-  - example: ` fix: mempool: Introduce a cache for valid signatures`
-  - `type`: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
-  - `scope`: api, chain, deps, mempool, multisig, networking, paych, proving, sealing, state, wallet
-- [ ] 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
+- [ ] PR title conforms with [contribution conventions](https://github.com/filecoin-project/lotus/blob/master/README.md#pr-title-conventions)
+- [ ] Update CHANGELOG.md or signal that this change does not need it per [contribution conventions](https://github.com/filecoin-project/lotus/blob/master/README.md#changelog-management)
 - [ ] New features have usage guidelines and / or documentation updates in
   - [ ] [Lotus Documentation](https://lotus.filecoin.io)
   - [ ] [Discussion Tutorials](https://github.com/filecoin-project/lotus/discussions/categories/tutorials)

.github/workflows/changelog.yml

@@ -30,10 +30,7 @@ jobs:
       - if: steps.changelog.outputs.modified == '0'
         env:
           MESSAGE: |
-            docs/changelogs/ was not modified in this PR. Please do one of the following:
-            - add a changelog entry
-            - add `[skip changelog]` to the PR title
-            - label the PR with `skip/changelog`
+            docs/changelogs/ was not modified in this PR. Please do one of the options in [changelog management conventions](https://github.com/filecoin-project/lotus/blob/master/README.md#changelog-management)
         run: |
           echo "::error::${MESSAGE//$'\n'/%0A}"
           exit 1

.github/workflows/pr-title-check.yml

@@ -18,13 +18,15 @@ jobs:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |
             const title = context.payload.pull_request.title;
+            # This should match https://github.com/filecoin-project/lotus/blob/master/README.md#pr-title-conventions
+            # 202408: Beyond Conventional Commit conventions, we also optionally suport the "scope" outside of paranenthesis for a transitionary period from legacy conventions per https://github.com/filecoin-project/lotus/pull/12340 
             const pattern = /^(\[skip changelog\]\s)?(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?:?\s(\w+:)?\s?[a-z].+$/;
             
             if (!pattern.test(title)) {
               await github.rest.pulls.createReview({
                 ...context.repo,
                 pull_number: context.payload.pull_request.number,
-                body: 'Please update the PR title to match one of the required formats:\n\n1. `<type>: <scope>: <subject>`\n2. `<type>(<scope>): <subject>`\n\nTypes: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test\nArea/Scope: api, chain, state, mempool, multisig, networking, paych, proving, sealing, wallet, deps\nSubject: start with lowercase\n\nOptionally, you can add "[skip changelog]" at the start of the title if the change does not require a CHANGELOG.md entry.',
+                body: 'Please update the PR title to match https://github.com/filecoin-project/lotus/blob/master/README.md#pr-title-conventions',
                 event: 'REQUEST_CHANGES'
               });
               core.setFailed('PR title does not match the required format');

CONTRIBUTING.md

@@ -0,0 +1,20 @@
+> 2024-08-08: this will get flushed out more soon as part of https://github.com/filecoin-project/lotus/issues/12360
+
+### PR Title Conventions
+PR titles should follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
+This means the PR title should be in the form of of `<type>(<scope>): <description>`
+  - example: `fix(mempool): introduce a cache for valid signatures`
+  - `type`: MUST be one of _build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test_
+  - `scope`: OPTIONAL arbitrary string that is usually one of _api, chain, deps, mempool, multisig, networking, paych, proving, sealing, state, wallet_
+  - Breaking changes must add a `!`
+  - Optionally the PR title can be prefixed with `[skip changelog]` if no changelog edits should be made for this change.
+Note that this enforced with https://github.com/filecoin-project/lotus/blob/master/.github/workflows/pr-title-check.yml
+
+### CHANGELOG Management
+To expedite the release process, the CHANGELOG is built-up incrementally.  
+We enforce that each PR updates CHANGELOG.md or signals that the change doesn't 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
+Note that this enforced with https://github.com/filecoin-project/lotus/blob/master/.github/workflows/changelog.yml