The shopify-api-js
repo uses changesets
to track and update the CHANGELOG.md
file, as well as to publish to NPM.
-
The developer creates a branch with their change using
main
as the base branch, opens a PR to obtain the necessary feedback, makes any required updates and obtains approval from the maintainers. -
The developer merges their PR, which merges their branch into
main
. This triggers themain-release.yml
workflow. -
The
main-release.yml
workflow will create a branch calledchangeset-release/main
and a corresponding PR calledPackages for release
(or update the branch and PR if they already exist). This branch/PR contains the necessary updates to theCHANGELOG.md
file that will be included in the release, as well as any updates (e.g., version) to thepackage.json
file. -
When ready to release, merging the
Packages for release
PR will updatemain
with the contents of thechangeset-release/main
branch, and will automatically publish the package(s) to NPM.
-
Prior to the development of breaking changes (for which pre-releases are being used), the
release-candidate
branch is created frommain
and put into pre-release mode using theyarn changeset
command (see details in the release candidates section below). -
The developer creates a branch with their change using
release-candidate
as the base branch, obtains the necessary feedback, makes any required updates and obtains approval from the maintainers. -
The developer merges their PR, which merges their branch into
release-candidate
. This triggers therelease-candidate.yml
workflow. -
The
release-candidate.yml
workflow will create a branch calledchangeset-release/release-candidate
and a corresponding PR calledPackages for release-candidate (rc)
(or update the branch and PR if they already exist). This branch/PR contains the necessary updates to theCHANGELOG.md
file that will be included in the release candidate, as well as any updates (e.g., version) to thepackage.json
file. -
When ready to publish the release candidate, merging the
Packages for release-candidate (rc)
PR will update therelease-candidate
branch with the contents of thechangeset-release/release-candidate
branch, and will automatically publish the release candidate package(s) to NPM. -
When ready to publish as the next general release, the
release-candidate
branch is taken out of pre-release mode using theyarn changeset
command (see details in the release candidates section below). -
Create a PR to merge the
release-candidate
branch intomain
and proceed as per the general release process above
See the sections below for specific details related to the steps outlined above.
-
Check the Semantic Versioning page for info on how to version the new release: http://semver.org
-
When creating a PR, the author should run the
yarn changeset
command, answer the relevant questions (i.e., is it major/minor/patch, what is the change description), then add and commit the new file tht was created in the.changeset
directory. These files are used by the workflows to construct theCHANGELOG.md
entries.Note If the change is very small and doesn't warrant a changelog entry, run
yarn changeset --empty
and commit the resultant file in the.changeset
directory.
-
Checkout the
changeset-release/main
branchgit checkout changeset-release/main
-
Update the version string in the
packages/shopify-api/lib/version.ts
file to match the version in thepackage.json
file in this branch. -
If needed, edit/remove any of the comments in the
CHANGELOG.md
files and commit them to thechangeset-release/main
branch. -
Once the files in the PR reflect the desired release changes, merge the
Packages for release
PR intomain
- this triggers the release. -
The same
changesets/action
in themain-release.yml
workflow will callyarn release
, which builds the packages and pushes the changed packages tonpmjs.org
. -
After the release, there will no longer be a
Packages for release
PR.changesets
will re-create it when a branch that containschangesets
-created changelog files is merged intomain
.
For significant API changes that could result in significant refactoring on the part of developers, consider releasing a few Release Candidate versions in advance of the final version.
Warning
These changes must be made against the
release-candidate
branch, so that the appropriate workflows can run (release-candidate.yml
).
Warning
Before commencing the effort for a batch of release candidates, make sure the
release-candidate
branch an identical copy ofmain
.
-
Prior to creating the first PR against the
release-candidate
branch, run theyarn changeset pre enter rc
command and commit the resultant files from.changeset
, including thepre.json
file. This informschangesets
that it is in pre-release mode, and that the pre-release tag isrc
. -
When creating a PR, the author should run the
yarn changeset
command, answer the relevant questions (i.e., is it major/minor/patch, what is the change description), and then commit the new file created in the.changeset
directory. These files are used by the workflows to construct theCHANGELOG.md
entries for the release candidates.Note If the change is very small and doesn't warrant a changelog entry, run
yarn changeset --empty
and commit the resultant file in the.changeset
directory. -
When the PR is merged into the
release-candidate
branch, therelease-candidate.yml
workflow uses thechangesets/action
to either create or update an existing PR that has the titlePackages for release-candidate (rc)
.
-
Checkout the
changeset-release/release-candidate
branchgit checkout changeset-release/release-candidate
-
Update the version string in the
packages/shopify-api/lib/version.ts
file to match the version in thepackage.json
file. Make sure to add an-rc.X
to the version, like so:7.0.0-rc.1
-
If needed, edit/remove any of the comments in the changed
CHANGELOG.md
files and commit them to thechangeset-release/release-candidate
branch. -
Once the files in the PR reflect the desired release changes, merge the
Packages for release-candidate (rc)
PR intorelease-candidate
- this triggers the release. -
The same
changesets/action
in therelease-candidate.yml
workflow will callyarn release
, which builds and pushes the release candidates tonpmjs.org
. -
After the release, there will no longer be a
Packages for release-candidate (rc)
PR.changesets
will re-create it when a branch that containschangesets
-created changelog files is merged intorelease-candidate
.
When a major set of changes is about to be mass released from the release-candidate
branch
Warning
The next steps need to be confirmed
-
Checkout the
release-candidate
branchgit checkout release-candidate
-
Take the
release-candidate
branch out of pre-release mode by runningyarn changeset pre exit
And commit the changed files.
-
Create a PR to merge the
release-candidate
branch intomain
. -
Once that PR is merged, follow the to perform a release outlined above.