Changesets

A Rust crate implementing Changesets. If you want a CLI which supports this format, check out Knope.

What can this do?

This crate programmatically works with changesets, and only concerns itself with the changeset formats and conventions. It specifically does not parse Markdown, bodies of changes are considered plain text.

Examples are not copy/pasted here, because it's hard to test them. So instead, here are links to common tasks:

• Create a change

What is a changeset?

Releasing a project requires two things at a minimum:

1. Setting a new version, preferably a Semantic Version.
2. Describing the changes in some sort of release notes, like a changelog.

The manual way to do this is to review all the changes since the last release, write a changelog, and decide on a new version. However, the longer you go between making the change (e.g., merging a pull request) and releasing the change, the more likely you are to forget something. This is especially true if you have a lot of changes, or if you have a lot of projects.

Changesets are a way of tracking changes as they happen, then bundling them up into a release. For each change you create a Markdown file containing which packages the change effects, how it effects them (in semver terms, and a Markdown summary of that change. For example, you might merge a PR which has these two change files:

.changeset/new_feature_to_fix_bug.md

---
changesets: minor
knope: patch
---

Added a feature to `changesets` to fix a bug in `knope`.

.changeset/new_feature_for_knope.md

---
knope: minor
---

This is a feature for Knope in the same PR

When you release, the knope package would contain both summaries in its changelog (and apply the greatest bump type), and the changesets package would contain only the first summary in its changelog.

This works very similarly to conventional commits, but does not rely on Git. You can use this together with conventional commits using a tool like Knope.

Terminology in this project

• Change: A single Markdown file (usually in the .changeset directory) describing a change to one or more packages. Note that this matches the original definition of changesets. A change contains a summary (in Markdown), a list of packages affected, and the semver "bump type" for each package.
• Change summary: The Markdown description of a change. This is the body of the change file. It should be included in the generated changelog.
• Bump type: One of none, patch, minor, or major, describing which components of a semantic version are affected by the change.
• Package: A releasable unit of code. Examples include a Rust crate, a JavaScript package, a Go module. A change can affect multiple packages.
• Changeset: A set of changes which will be released together. Notably, this differs from the original definition of changesets, which is does not have a term for the bundle of multiple changes. A changeset may affect any number of packages.
• Release: The part of a changeset that applies to a single package and determines how that package is released.