workspace-release

DO NOT USE THIS PACKAGE: IT IS A TEST PACKAGE AND WILL BE MOVED TO IT'S FINAL HOME

workspace-release is a tool for bumping semantic versions in a workspace/monorepo, adhering to the Conventional Commits standard. It can also generates a CHANGELOG.md file for each package in the workspace/monorepo along with support for generating custom changelog web pages.

WARNING: we use the name in package.json as part of the release process. we generate a tag with the package name + version (example tag: @org/[email protected]) and use that tag in future releases to find out which files have changed. If you change the package name, you'll need to add a git tag with the existing version and new package name.

Features

• super easy to setup and use
• workspace/monorepo agnostic. in fact, you don't even need to have a monorepo setup for workspace-release to work.
• builds a CHANGELOG.md file for each package and the github repo itself
  • you can replace your existing release utilities because we completely rebuild the CHANGELOG.md files on every release.
• bumps package versions in all your packages
  • tags references using @org/packagename@version enabling tracking of versions in the same repository

NOTE: there are currently no command line options. if you need command line options to chnage the defaults, create a github issue and we'll try add the command line option.

Setting up workspace-release

For each package that you want to generate a CHANGELOG.md file, bump the package version and publish the changes to a registry (like npmjs.com):

1a) Add to package.json a release amd publish script. You can name it anything but we recommend ci:release and ci:publish

{
  "scripts": {
    "ci:release": "npx workspace-release release",
    "ci:publish": "npx workspace-release publish"
  }
}

3. In your pnpm workspace/monorepo add recursive calls using pnpm (use a similar approach if you are using other package managres like npm, lerna, etc.).

{
  "scripts": {
    /// release all of the packages && then release the workspace
    "ci:release": "pnpm run --recursive ci:release && pnpm workspace-release release",
    /// note that we don't publish the workspace
    "ci:publish": "pnpm run --recursive ci:publish",
  }
}

Setup Publishing to npmjs.com

1. Create an account at https://www.npmjs.com/signup.
2. Generate a CLASSIC AUTOMATION access token at https://www.npmjs.com/settings/erichosick/tokens.

• note the token

3. In ~/.npmrc (or whever that file is). Add the following:

//registry.npmjs.org/:_authToken={your_automation_token}

Using workspace-release locally

To release run pnpm ci:release from the root of the project. This will bump the versions of all packages that have relevant changes since the last release

Now that all versions are bumped, we can safely publish all of the packages by running pnpm ci:publish from the root of the project.

With all versions bumped, we can rely on pnpm workspace to update all the versions within the package.json with the latest version.

How workspace-release works

Our approach is:

1. run git log @org/[email protected]:
2. filter out any files that are not part of the package workspace-release was ran in
3. for the filtered commit messages and using the conventional commits standard standard:
   • we bump the version
   • we update/re-build the package CHANGELOG.md
4. We add a tag of @org/[email protected] for each package that had a version bump.

IMPORTANT: Because of the way workspace-release works, we recommend that you create commits that only contain files from a single package: stacking up multiple commits on a single branch.

Setting up CI/CD Workflow

workspace-release can be used in your CI/CD workflow in any way you like. following is an example workflow:

1. in main, run pnpm ci:release (manually or via ci/cd)
2. optionally publish to npmjs by running pnpm ci:publish

NOTE: by default, workspace-release must be ran in main and the git barnch must be clean (no unstaged changes, untracked files, etc.).

Github Actions CI/CD

1. For the repository you want to run workspace-release, go to https://github.com/{organization}/{repository}/settings/environments and add a PACKAGE_REGISTRY_ACCESS_TOKEN environment variable. For npmjs.com add the value generated by following the steps in Setup Publishing to npmjs.com.
2. Add the

Works Well With

We recommend:

• pnpm: as the package manager
• nx: for quick parallel builds

Questions

Why do I have to add ci:release to every package?

We don't know anything about your workspace/monorepo or CI/CD process. In fact, workspace-release can even work without a workspace/monorepo. All we know how to do is look at the commit logs, filter for changes on a specific package, and update/generate log files like CHANGELOG.md files.

Why Did We Make This

There are a lot of requests to support workspace/monorepo changelog.md files. There are work arounds for some of the tools that bump versions and generate changelogs but nothing that focuses 100% on workspacess/monorepo. We designed this from the ground up as being workspace/monorepo centric.

Example features request:

• Show changelog only for changes in a subfolder

Other Information

To be added.