import { Meta, Title } from '@storybook/blocks';

<Meta title="Release workflow" />

<Title>Release workflow</Title>

## Versioning

This project versions components independently, meaning each component has its own version number, updated independently of other components. We follow [semantic versioning](https://semver.org/) and as such, each release is versioned according to the following rules:

- **Major**: Breaking changes such as API changes, the removal of features, or changes to `--mod` custom properties
- **Minor**: New features or enhancements
- **Patch**: Bug fixes or minor improvements

Versioning (and package publishing) is handled by [Changesets](https://github.com/changesets/changesets), which lets contributors declare how their changes should be released.

Additionally, we use the [Conventional Commits](https://www.conventionalcommits.org/) specification for writing our commit messages to help communicate the types of changes we're making to the codebase.

### Changesets usage

A changeset is a piece of information about changes made in a branch or a commit. It holds three bits of information:
* What we need to release
* What the next version we want to release is (using a [semver bump type](https://semver.org/))
* A changelog entry for the released packages

Not every change to the codebase will require a release, but any changes to files within the `/components` directory **will** require a release. Generally, when thinking about versioning and releases, it's a good idea to consider the question: "does this change need to be consumed by someone or something outside of Spectrum CSS?" If the answer to that question is "yes", then the changes will likely require a changeset.

A changeset can be [added locally by the author](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md#i-am-in-a-multi-package-repository-a-mono-repo) by invoking the command line script, or it can be added during the Pull Request process by a project maintainer via the [Changesets GitHub bot](https://github.com/changesets/bot). The result of either method will be a single commit that adds a markdown file with YAML frontmatter describing the changes.

Additionally, [multiple changesets](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md#tips-on-adding-changesets) can be added to a Pull Request.

## Releasing

Releases are handled via Changesets. Specifically, via the [Changesets GitHub action](https://github.com/changesets/action). When there are new changesets on the [configured baseBranch](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md#basebranch-git-branch-name) (usually `main` in our repo), the action will create a new Pull Request with all of the package versions updated and changelogs updated. The Pull Request can then be merged back into `main` and the updated packages can be published manually or automatically via the action.

This allows for maintainers and contributors to review the proposed version and changelog updates and make changes as necessary before the publish step.

## Prereleases

Information about Changesets and prereleases can be found [here](https://github.com/changesets/changesets/blob/main/docs/prereleases.md).
