Formally document and use https://www.conventionalcommits.org/en/v1.0.0/ or similar for how we write commits and branches

[drewbo]

Initial scope to the pages-core repo to help inform our process.

Acceptance Criteria

• Add all docs to repository README
• Add documentation on how to write commits
• Add docs on how to rebase/group commits
• Document the Github Ruleset used for commits

[drewbo]

The irony of not being able to close the issue because the PR won't merge!

Right now we're at a bit of an impasse with the rules I've created because merge commits aren't valid conventional commits but my efforts to get rid of them create scenarios where we have unverified commits. I see two general paths forward:

• We enforce linear history going forward which allows for strict testing of new commit messages, easier generation of changelogs. However this also means that if we want to keep the "branch must be updated" rule in place, we'll have to manually rebase each commit to the latest on default (updating via the UI, even with rebase, will create an unverified commit)
• We allow merge commits in PRs and via "update branch". Then we'll need to adjust or allow bypassing of our conventional commits ruleset. This will also make generating new releases/automated changelogs a little bit harder.

I'm in favor of the second option because I'd rather make this set of tickets more difficult and have our checking be a little less strict but create lower barriers to merging in the future.

[apburnes]

The first option seems untenable based on the deviation from our branch ruleset and current workflow. With the second option, would we have to write our action to account for the PR merge commits when generating the changelog?

[drewbo]

@apburnes i think yes, but we're already going to require some customization with our "release/deploy/changelog" part of the pipeline (signing commits, running ideally in concourse) so it's fine to assume some extra work there. I'll move forward with option two and update the documentation accordingly

[pburkholder]

I'm only tracking loosely here, but: are you doing this to hew more closely to what the rest of Cloud does, or something different?

If you're feeling ambitious, I'd ❤️ someone updating our config mgmt plan at https://cloud.gov/docs/ops/configuration-management/ but that's likely out of your scope....

[drewbo]

Right now we don't have a tagging/release scheme for Pages and this is an effort towards that. But I agree that we should look at the linked page and https://github.com/cloud-gov/product/blob/main/StoryLifecycle.md soon (in conjunction with platform teams) and both could use an update or some communication to ensure we're still adhering to that