Publish versions

How to publish a version

• Apply the Changesets
• Commit all the changes
• Create/Update the release branches
  • Major changes
  • Patch or minor changes
• (Optional) Deleting unsupported old releases
• Push all the branches
• (Optional) Creating a git tag
• (Optional) Creating a GitHub release
  • Using GitHub
  • Using GitHub CLI
• (First version only) Enabling GitHub Pages
  • Using GitHub
  • Using curl
• (Optional) Publish the new version on npm

Apply the Changesets

pnpm run changeset:version

Commit all the changes

1. Add all the changes: git add ..
2. Commit all the changes: git commit.

Create/Update the release branches

Major changes

The release branch should not exist. If it does, remove it before continuing.

Run git branch releases/MAJOR master where MAJOR is the new major version.

Patch or minor changes

The release branch should already exist. If not, follow the subsection above.

Run git fetch . master:releases/MAJOR where MAJOR is the current major version.

(Optional) Deleting unsupported old releases

It is recommended to support the last two or three major versions, this means that bug fixes and security updates can be backported via release branches.

If you do not plan to support a previous release, you must delete its branch. This will cause the related documentation to be pruned on the next CI run.

1. Remove the branch locally: git branch -d releases/OLD_MAJOR, where OLD_MAJOR is the unsupported major version.
2. Remove the branch on the remote: git push --delete releases/OLD_MAJOR.

Push all the branches

git push origin --all --set-upstream

Note: This will run the CI to update the documentation. Please wait until the CI is passing before continuing.

(Optional) Creating a git tag

• Run git tag -a v1.2.3 where 1.2.3 is the version in package.json
• Push the tag: git push origin --tags.

(Optional) Creating a GitHub release

Using GitHub

1. Open the repository.
2. Press on “Releases”. If it is not visible, press on “tags” and then select “Releases”.
3. Press on “Create / Draft a new release”.
4. Enter the tag version v1.2.3 where 1.2.3 is the version in package.json.
5. Copy the tag version into the release title.
6. Copy the correct section of the CHANGELOG.md into the description.
7. Press on “Publish release”.

Using GitHub CLI

Note: In this section, 1.2.3 is the version in package.json.

Extract the correct section from the CHANGELOG.md into CHANGELOG-v1.2.3.md and then run the following command:

gh release create v1.2.3 \
  --title v1.2.3 \
  --notes-file CHANGELOG-v1.2.3.md

Following the command, the file CHANGELOG-v1.2.3.md is no longer needed and can be deleted.

(First version only) Enabling GitHub Pages

GitHub Pages host the documentation files. However, The documentation CI only creates the gh-pages branch once there is at least one release branch.

Using GitHub

1. Open the repository
2. Press on “Settings”.
3. In the sidebar, press on “Pages”.
4. Select gh-pages from the first drop down.
5. Select / (root) from the second drop down.
6. Press on “Save”.

Using curl

Note: This API currently is a preview, and might change in the future.

Run the following command, where USER/REPO is the name of the repository. This might require a personal access token.

curl \
  -X POST \
  -H 'Accept: application/vnd.github.switcheroo-preview+json' \
  repos/USER/REPO/pages \
  -d '{"source":{"branch":"gh-pages","path":"/"}}'

(Optional) Publish the new version on npm

This can not be undone easily, double check if everything is correct.

pnpm publish