Automate mithril's release workflow

[JAForbes]

Automated releases, pre-releases, (code) rollbacks and recovery, npm publishing, change log management just by using normal github flow.

Description

Release PR with automated changelog and semver

Any time a feature branch is merged into a next, a release PR from next -> main will automatically be created/updated with a summarized changelog section and automated semver version.

Upon merge of this release branch, the changelog section will be extracted and prepended into a changelog.md. Additionally the package.json version will be applied. Both these changes will be reflected on next and main as pr-release guarantees a fast-forward merge. This ensures new feature branches that branch from next have the latest artifacts.

Pre-releases

Additionally, on every feature merge into the next branch, a pre-release will be published on the @next channel with a next preid. This allows for the community to test out mithril builds in real world apps prior to a public release.

Rollbacks

If something gets merged into main that shouldn't have, just run the rollback action. It will identify the changes between the most recent release and the prior release, it will then backup the current state of main and next in a new branch, and add a new commit which reverses those changes. It then takes the changes that were removed and opens a new rollback recovery branch targeting next.

This allows the maintainers to merge other unrelated changes into production/latest while debugging/investigation can continue in parallel against the rolled back changes. Note this does not unpublish, or publish a new npm version, as rollbacks are always a case by case basis and pr-release cannot guess how the maintainer would want to handle rolling back packages or deployments.

Motivation and Context

To help the mithril community release more rapidly, and to lower the barrier of entry for other maintainers to help with releasing changes.

How Has This Been Tested?

I have forked mithril and mirrored the config on the fork. I changed the package name to harth-mithril and publishes releases and pre-releases automatically ( npm )

I also tested rollbacks with selective recovery.

Additionally I helped @StephanHoyer add pr-release to StephanHoyer/classies and used it in my own packages and the product my company works on.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation change
• Maintainer Workflow / Automation

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.
• I have updated docs/changelog.md

[JAForbes]

We'll probably need to discuss what to do with the existing changelog and the new one. pr-releases one simply pre-prends the exact text from the generated changelog section into changelog.md in the root of the project. The path is configurable, but I am not sure if simply prepending to the docs/changelog.md is the right approach as that document is more curated.

Maybe we should have a recent-changes.md which is managed by pr-release, and then we retain the manually maintained docs/changelog.md for the website, which can capture important developments, but not include general housekeeping. Or maybe the website build can concatenate the two files into one page. I think both files are important.

[StephanHoyer]

Regarding changelog: Maybe we use two files for now and see if the hand curated on is worth it in the long run. If the PR-descriptions are good enough it might enough to keep the autogenerated one.

Other than that: Great work. Will take a closer look later today!

[StephanHoyer]

Great work! Thanks @JAForbes

• could you update/remove the scripts/release.js and docs/releasing.md to reflect the new process?
• Maybe add a small notice to the readme that release is done by prr
• How would a first release work?
• When do we want to do this (would be great to do this together)?
• let's create a new auto-changelog file, name it as you want

[dead-claudia]

I like it and am tempted to use it for my own purposes, but I have two main questions:

1. What's the file structure look like and how does it interact with our existing changelog file?
2. How will we enforce the necessary labels to determine release scale, and what would happen when we inevitably end up forgetting to ensure those labels exist?

[JAForbes]

@StephanHoyer

could you update/remove the scripts/release.js and docs/releasing.md to reflect the new process?

Yep will take a look now.

---

Maybe add a small notice to the readme that release is done by prr

👍

---

How would a first release work?

When we merge this in to next, it will automatically create its own release PR incrementing semver patch in the title of the PR and it will publish a prerelease on the next channel. When we merge that, it will auto publish that patch on the latest channel, update the package.json version, and create a github release.

---

When do we want to do this (would be great to do this together)?

Yeah maybe we can do it sometime this coming week when we're both awake. Maybe 8pm AEDT / 10am CET.

It is entirely possible there'll be some minor config issues and we'll need to do a few hot fixes, but they won't affect mithril consumers, just require another PR. Things like permissions not being configured, invalid yml files, missing or misconfigured secrets etc. Once it is set up though it will be stable.

---

let's create a new auto-changelog file, name it as you want

Ok cool, I'll call it recent-changes.md?

---

@dead-claudia

What's the file structure look like and how does it interact with our existing changelog file?

The PR description has html markers that demarcate specific sections. Some of these sections are automatically updated as each merge into next occurs. But otherwise, the content is left alone. The changelog sections are then extracted and prepended verbatim into the changelog.md file (or whatever filepath we chose).

Demarcated HTML comments in PR description

Prepended changelog content

Release description body

We can also output metadata from pr-release to use in our doc generation: see https://pr-release.org/scripting/

Effectively all metadata is extractable as json but also as individual text and markdown files. So we can inject whatever data we need about a release into whatever format we want.

---

How will we enforce the necessary labels to determine release scale, and what would happen when we inevitably end up forgetting to ensure those labels exist?

Every time a branch is merged in, a preview of the pending semver version will render in the title and the body. If it looks wrong, or if a maintainer forgot to add the correct label, you can manually edit the labels post merge of the feature branch and re-run the pr action. The PR description will be safely updated and the correct new version will appear.

Bottom line: if the version in the release PR version looks wrong, the maintainer can update it, if the release PR version looks right, then merge away.

If for some reason the version is incorrectly merged, it would be similar to a contributor updating the package.json version in a PR without the maintainer noticing, same risk profile, but arguably a lot easier to spot in pr-release's case as it is in the header / title of the release PR.

[dead-claudia]

@JAForbes

When we merge this in to next, it will automatically create its own release PR incrementing semver patch in the title of the PR and it will publish a prerelease on the next channel. When we merge that, it will auto publish that patch on the latest channel, update the package.json version, and create a github release.

Is this for all such merges, or is it only for the first? I assume it's for all, as that would be consistent with your response to my questions?

[JAForbes]

@JAForbes

When we merge this in to next, it will automatically create its own release PR incrementing semver patch in the title of the PR and it will publish a prerelease on the next channel. When we merge that, it will auto publish that patch on the latest channel, update the package.json version, and create a github release.

Is this for all such merges, or is it only for the first? I assume it's for all, as that would be consistent with your response to my questions?

Yeah all merges. Because next is the default branch, the moment this lands in next, github will activate the workflow yml files. And then it will detect that a feature branch just merged into next, and do what it normally does.

[StephanHoyer]

Yeah maybe we can do it sometime this coming week when we're both awake. Maybe 8pm AEDT / 10am CET.

Sounds great! Choose a day, I'm open to all.

[dead-claudia]

LGTM modulo the two remaining nits in comments:

• Spaces -> tabs
• Better to upgrade now than to punt it until later - that way we know it'll get done and it's also less work (and potential headache) than splitting it into two separate reviews

[JAForbes]

LGTM modulo the two remaining nits in comments:

• Spaces -> tabs
• Better to upgrade now than to punt it until later - that way we know it'll get done and it's also less work (and potential headache) than splitting it into two separate reviews

Yeah I need to retest end to end on the fork anyway for the separate changelog file. Also I may as well put the doc publishing into the merge.yml, so I'll test the new checkout version too.

[StephanHoyer]

Great too see more an more stuff removed from mithril.js 🎉

[JAForbes]

I've pushed the requested changes. But I still want to do an end to end run through on the fork, so let's hold off merging.

I need to verify...

• release/rollback etc works with v3 of setup-node (it should)
• build-docs works in the CI context of merge.yml
• And check --out recent-changes.md behaves as expected

Actually just realised build-docs isn't enough, need to commit/push to gh-pages in CI, I forgot because the doc publishing on my other fork deployed to s3.

It would be really clean to do that within pr-release because we already dynamically create git trees 100% in octokit and publishing artifacts to gh-pages seems within scope of that project.

I'll remove build-docs and we can do that afterwards, automating releases of the library is enough for one PR, docs can come soon after.

[JAForbes]

I just reverted the tabs change, TIL yaml outlaws the use of tabs. When I was testing on my fork, the highlighting for the entire file went red when tabs were used.

[StephanHoyer]

Are we ready to merge this now?
@dead-claudia @JAForbes

[JAForbes]

I want to do another round of testing. The last test I did wasn't sufficient.

[dead-claudia]

I'll wait for this next round of testing before approving.

[JAForbes]

@dead-claudia / @StephanHoyer tested and ready to go. Apologies for the delay.

[dead-claudia]

In addition to the questions and nits, please revert the package-lock.json update - it's diff noise.

[StephanHoyer]

Great work, looking forward to merge this. Thanks @JAForbes