From 75b4d2efdd9e547841d4f752aac7de788270df8b Mon Sep 17 00:00:00 2001 From: Jean-Yves Moyen Date: Fri, 11 Oct 2024 11:48:36 +0200 Subject: [PATCH] Add info on Alfa changesets (#1700) --- docs/guides/changeset.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/docs/guides/changeset.md b/docs/guides/changeset.md index 726ce363ce..a25122001a 100644 --- a/docs/guides/changeset.md +++ b/docs/guides/changeset.md @@ -10,16 +10,35 @@ $ yarn changeset and follow the flow, see more instructions at [Adding a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md). -Remember: +## Guidelines +- Alfa follows [Semantic Versioning](https://semver.org/). Use the appropriate bump type for the changeset. - As long as Alfa is in version 0.*, no **major** bump should be recorded. Anything that would normally require a major bump instead uses a minor bump. - Always prefer using the full editor (i.e. submit empty changeset on the CLI to trigger the editor). This lets you enter both a title (first line) and details for the change. - The changelog entry is already tied with the Git PR. No need to add it. Focus on what concise info is needed for consumers to adapt their code or understand a different behaviour. - On the other hand, changeset can contain short references to Github issues (`#1234`) that will be auto-linked in the changelogs. - Not all changes require changesets. A changeset is only needed with changes of public API (call signatures), or behaviour (bug fixes); a changeset is not needed for update to documentation, refactoring, … -- A single PR may add several changesets. Sometimes, it makes sense to touch several bits in one PR, and each may require a specific changeset. Each changeset will generate a separate Changelog entry; so when it makes sense to have two changelog entries, then it makes sense to have two changesets. +- A single PR may add several changesets. Sometimes, it makes sense to touch several bits in one PR, and each may require a specific changeset. Each changeset will generate a separate Changelog entry; so when it makes sense to have two changelog entries, then it makes sense to have two changesets. A single PR may even add several changesets at different bump levels. - A single changeset may affect several packages. Sometimes even an atomic change is touching things in a few places; then it makes sense to have a single changeset to group them. -When a changeset is created, a new file is added to `.changeset/unique-id.md`; this file needs to be added to git and committed! The changeset is then part of the PR and can be reviewed in context. +When a changeset is created, a new file is added to `.changeset/unique-id.md`; this file needs to be added to git and committed! The changeset is then part of the PR and can be reviewed in context. It may also be edited by a later PR if that makes sense. PRs without changeset will get a warning by the changeset bot. This is not blocking the PR since not all changes require change sets… + +## Alfa changesets + +Alfa changesets have the following shape: + +```markdown +**[kind]:** [title] + +[details] +``` + +Where `[kind]` is one of `Fixed`, `Changed`, `Added`, `Removed`, `Breaking`. As a rule of thumb, `Breaking` and `Removed` kinds require a major bump (minor as long as we are in version 0.*); `Added` requires a minor bump; `Fixed` requires a patch bump; `Changed` may be minor or patch bump depending on the exact change, but should not be major (a change requiring a major bump is usually `Breaking`). + +The `[title]` will be included in the [global changelog](../../CHANGELOG.md). It should be a one-liner short description of the change. Consider the information that a consumer would need to know in order to update the version of Alfa they use. + +The `[details]` are only included in the individual changelog of the corresponding package(s). They are most often not needed. They can most notably contain migration instructions in case of breaking changes. + +The overall structure, as well as the allowed `[kind]` are validated automatically. We currently do not have validation that the `[kind]` matches the bump type as it is a bit less clear cut. \ No newline at end of file