mcmire
commented
2 years ago Here are my thoughts on what sort of changes we could make to this action in order to achieve this goal.
Disclaimer
It's important to know up front that right now this action reads the version we want to release (the "release version") from the branch being merged. This is being changed in #46 to read from the version in package.json, so we will assume that.
Current flow
Once we know what the release version is, we follow one of two workflows:
Polyrepo
- We parse
CHANGELOG.mdand extract the section of the changelog that matches the release version. - We then use the
ghcommand-line utility to create a new GitHub release which is titled the same as the release version and has the content of the section of the changelog as obtained in the previous step. - We then create a Git tag which is named
v${releaseVersion}(e.g. if the release version is1.2.3, the tag will be calledv1.2.3).
Monorepo
- Instead of reading
CHANGELOG.mdin the root, we go through all of the packages that the monorepo holds (as specified via the rootpackage.json'sworkspacesfield), and for each package, we extract the section of itsCHANGELOG.mdthat matches the release version. We stitch these sections into one big changelog, where each section is headered by the package that it belongs to. - We then use the
ghcommand-line utility to create a new GitHub release, using the release version for the title and the big changelog as obtained in the previous step as the release notes. This will end up also creating a Git tag which is namedv${releaseVersion}(e.g. if the release version is1.2.3, the tag will be calledv1.2.3).
New flow
For polyrepos, everything should work how it works now.
But for monorepos, there's a problem with the existing flow: it assumes that when a release is created, all packages will be bumped to the same version. This may continue to be true for snaps-skunkworks and eslint-config, but will not be true for controllers, because we will be following an independent versioning strategy, where 1) every package can have a different version and 2) not every package may be bumped when a new release is issued.
Therefore, the changes we need to make are as follows:
- We will want to have the action take a second input, which is the version synchronization strategy. By default, to avoid breaking changes for
snaps-skunkworksoreslint-config, we can default this strategy to "fixed", but allow it to be set to "independent". - For the "fixed" versioning strategy, we want to continue to follow the same flow as provided above.
- But for the "independent" strategy, we want to follow this flow:
- We may want to change the representation of the release version. Again, this is the same as
versionlisted in the root package'spackage.json. The root package is private, so as it stands, assigning a version like<major>.<minor>.<patch>to this package doesn't make sense. It may make more sense to assign a date, such as<year>.<month>.<day>. To account for the case in which we want to create more than one release in a day, we may want to add a fourth part, so in order to stay SemVer-compatible, the format could be<year>.<month>.<day>-<release number>. (Thesemverlibrary should be able to handle this, but we can check.) The "release number" here would be a number that would be incremented for each new release. We would probably want to ensure that this number is valid by pulling the latest of the set of Git tags that matches this format, and (assuming that such a tag exists) confirm that the new version increases the number at the end by 1. - In the existing workflow, we iterate through all of the workspace packages in order to extract sections of changelogs from each package, but now we only want to iterate through the packages for which we want to release new versions. The easiest way to find this, I think, is to go through each package in the monorepo and compare the version of that package as set in its
package.jsonto its currently published version on NPM. Any packages where these two versions differ we can assume require new releases. - Once we have a list of packages to release, we can go through each package and extract a section of its
CHANGELOG.md— only instead of using the release version to find the appropriate section, we use the version inpackage.jsonfor that package. As before, though, we then stitch the sections of the changelogs from each package into one big changelog, where each section is headered by the package that it belongs to. - We then use the
ghcommand-line utility to create a new GitHub release, using the big changelog from the previous step as the release notes. For the title, however, we can parse the date from the release version, so for example,2022.6.30-1234might turn into "June 30, 2022 (release 1234)". We can also instruct theghcommand to create a Git tag named after the release version — although we can drop thev, since it's not a real version. - Finally, we will want to create Git tags for each package that we are releasing (so we will have a tag per root release, and a tag per package release). We already have the list of packages from a previous step, so we can simply iterate through all of them and call
git tag <new version>, then callgit push --tagsat the end. (Note that in order to do this, we may want to move the entire of contents ofscripts/create-github-release.shinto the TypeScript script. That may make things easier to test.) - Of course, we want to make sure this logic is well tested.
- We may want to change the representation of the release version. Again, this is the same as
Decisions to make
In summary, here are the things we need to decide, in the case of a monorepo with an independent versioning strategy:
- What should the release version be called?
- How should we title each GitHub release?
- Should the content of
scripts/create-github-release.shbe folded into the TypeScript code?
Prior art
For inspiration, take a look at Vercel, which more or less follows the same process that we want to follow: https://github.com/vercel/vercel
Currently this action only supports monorepos with synchronized versions. We will soon be using monorepos that don't use synchronized versions, so this will need to be updated to support that.