|
| 1 | +--- |
| 2 | +name: beachball-change-file |
| 3 | +description: How to create a Beachball change file. ONLY use this skill when the user asks to generate change files, before pushing a branch, or before creating a PR. |
| 4 | +metadata: |
| 5 | + version: 1.0.2 |
| 6 | + source: https://github.com/microsoft/beachball/blob/main/.claude-plugin/plugins/beachball-change-file/skills/beachball-change-file/SKILL.md |
| 7 | +--- |
| 8 | + |
| 9 | +[Beachball](https://microsoft.github.io/beachball/) is a tool used for managing versioning and changelogs for JS/TS codebases. Every pull request must include a Beachball change file. Change files include the list of packages with public-facing changes in the branch, with the description and semver change type for each package. After the PR is checked in and a release is run, the change files are used to determine version bumps and update changelogs. |
| 10 | + |
| 11 | +Beachball normally uses a CLI with an interactive prompt to create change files, but they can also be created manually using the standardized JSON format detailed below. |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +- Deterine the root directory: this is almost always the git root, but the user might specify a different folder. (The root usually contains `beachball.config.*` or `.beachballrc.*` or has a `"beachball"` key in `package.json`.) |
| 16 | +- Determine the package manager for the repo (`npm`, `yarn`, `pnpm`). The example commands below assume `yarn`, but substitute the appropriate command runner syntax for a different package manager. |
| 17 | +- Check the root `package.json` `scripts` for scripts that run `beachball change` and `beachball check`. |
| 18 | + - The examples below assume `scripts` called `change` and `checkchange` respectively, but substitute the appropriate script names if found. |
| 19 | + - Using `scripts` if defined is preferred since they may add extra arguments, but it's possible to run the commands directly: `yarn beachball change` and `yarn beachball check` (substituting appropriate command runner) |
| 20 | +- Use `beachball config get` to check the following settings (note: `beachball config get` only exists in versions `>= 2.64.0`) |
| 21 | + - `yarn beachball config get changeDir`: where to put the change files |
| 22 | + - `yarn beachball config get branch`: target branch name |
| 23 | + - `yarn beachball config get groupChanges`: whether grouped change files are enabled (true/false/undefined) |
| 24 | + |
| 25 | +## Creating and validating a change file |
| 26 | + |
| 27 | +Usually, an AI agent should create a change file manually following the standardized format detailed below. |
| 28 | + |
| 29 | +### 1. Validate repo state |
| 30 | + |
| 31 | +Beachball only considers staged and committed files, so you should check for unstaged or untracked changes before proceeding: |
| 32 | + |
| 33 | +1. Get file paths with unstaged changes (`git ls-files -m`) and untracked changes (`git ls-files -o --exclude-standard`) |
| 34 | +2. If there are any unstaged or untracked changes, ask the user whether they would like to stage all files or continue without staging. If they choose to stage, run `git add .` before proceeding. |
| 35 | + |
| 36 | +### 2. Get changed packages |
| 37 | + |
| 38 | +Run `yarn checkchange --verbose` to get the list of changed packages and files considered by `beachball`: |
| 39 | + |
| 40 | +- The list of changed packages is under "Found changes in the following packages" -- you must ONLY include these packages in the change file! (beachball has various settings to ignore packages or files) |
| 41 | +- The list of changed files is under "changed files in current branch". IGNORE any files with `~~` strikethrough formatting. |
| 42 | + |
| 43 | +### 3. Create the change file(s) |
| 44 | + |
| 45 | +Change files are located under `<changeDir>`. There are two possible structures for change files, determined by the `groupChanges` setting. |
| 46 | + |
| 47 | +#### Case 1: Non-grouped format (`groupChanges` is `false` or unset) |
| 48 | + |
| 49 | +If `groupChanges` is `false` or unset, you should create a separate change file for each package. |
| 50 | + |
| 51 | +For each changed package **as listed by beachball**: |
| 52 | + |
| 53 | +1. Generate a random GUID: `node -e "console.log(crypto.randomUUID())"` |
| 54 | +2. Create a change file under `<changeDir>/<packageName>-<guid>.json` with the following format. See [Change entry values](#change-entry-values) below for the proper values of each field. |
| 55 | + |
| 56 | +```json |
| 57 | +{ |
| 58 | + "packageName": "", |
| 59 | + "type": "", |
| 60 | + "dependentChangeType": "", |
| 61 | + "comment": "", |
| 62 | + "email": "" |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +#### Case 2: Grouped format (`groupChanges: true`) |
| 67 | + |
| 68 | +If `groupChanges` is `true`, you should create a single change file. |
| 69 | + |
| 70 | +1. Generate a random GUID: `node -e "console.log(crypto.randomUUID())"` |
| 71 | +2. Create a single change file under `<changeDir>/change-<guid>.json` with the following format. The `changes` array should have an entry for each changed package **as listed by beachball**. See [Change entry values](#change-entry-values) below for the proper values of each field. |
| 72 | + |
| 73 | +```json |
| 74 | +{ |
| 75 | + "changes": [ |
| 76 | + { |
| 77 | + "packageName": "", |
| 78 | + "type": "", |
| 79 | + "dependentChangeType": "", |
| 80 | + "comment": "", |
| 81 | + "email": "" |
| 82 | + } |
| 83 | + ] |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +### 4. Validate the change file(s) |
| 88 | + |
| 89 | +Run `git add <changeDir>`, then re-run `yarn checkchange` to verify. |
| 90 | + |
| 91 | +## Change entry values |
| 92 | + |
| 93 | +Each package's entry has the following values: |
| 94 | + |
| 95 | +- `packageName`: The name of the changed package, e.g. `just-task` |
| 96 | +- `type`: The semantic versioning change type for the package. See [Determining a package's change type](#determining-a-packages-change-type) below. |
| 97 | +- `dependentChangeType`: Change type for packages that depend on this package. If `type` is `"none"`, this should be `"none"`. Otherwise, this should be `"patch"` (beachball internally handles this for the special case of prerelease packages). |
| 98 | +- `comment` (`--message` CLI arg): A concise description of the changes made to the package. Tips: |
| 99 | + - This will go in the changelog, so it should focus on user-facing changes (especially any API changes) rather than implementation details. |
| 100 | + - Markdown formatting is allowed, so any references to names from code should be wrapped with backticks. |
| 101 | +- `email`: User's email from `git config user.email`, or `"email not defined"` if not available. Do NOT invent an email. |
| 102 | + |
| 103 | +### Determining a package's change type |
| 104 | + |
| 105 | +The `type` field is the semantic versioning change type for the package, determined based on the diff content of changed files in that package. There are different options depending on whether the package's current version contains a prerelease suffix or not, and the `disallowedChangeTypes` setting may modify which change types are allowed. |
| 106 | + |
| 107 | +If you're still uncertain about the change type after following the instructions below, ask the user to choose. |
| 108 | + |
| 109 | +For each package, start by checking: |
| 110 | + |
| 111 | +- The current `version` in `package.json` |
| 112 | +- `disallowedChangeTypes` for the specific package: `yarn beachball config get disallowedChangeTypes --package <packageName>` |
| 113 | +- Whether the package has a file `<package path>/etc/*.api.md`. If so, the diff of this file will show whether any public API signatures changed. |
| 114 | + |
| 115 | +#### Case 1: Version is 1.0.0 or greater and NOT prerelease |
| 116 | + |
| 117 | +If the package's current version is 1.0.0 or greater and does NOT have a prerelease suffix, the typical options are `<patch|minor|major|none>` (but you MUST respect `disallowedChangeTypes`): |
| 118 | + |
| 119 | +- `"patch"`: Bug fixes or other changes that don't impact exported API signatures. |
| 120 | +- `"minor"`: New exported APIs, non-breaking signature changes to exported APIs, or more significant changes to internal logic. (If the package has a `<package path>/etc/*.api.md` file, checking its diff is the easiest way to see exported API changes.) |
| 121 | +- `"major"`: Breaking changes to exported APIs (removals or breaking signature changes), critical dependency updates, or behavior changes that might be breaking for the consumer. You MUST confirm with the user before choosing `"major"`. |
| 122 | +- `"none"`: None of the changes will impact consumers of the package (e.g. the changes are only to non-exported test-specific files or documentation). If you're not certain, prefer `"patch"`. |
| 123 | +- There are additional options `prerelease|premajor|preminor|prepatch`, but you should only use one of these if explicitly requested by the user. |
| 124 | + |
| 125 | +#### Case 2: Version is 0.x.y and NOT prerelease |
| 126 | + |
| 127 | +If the package's major version is 0 and does NOT have a prerelease suffix, this is similar to case 1. However, version 0 packages follow different conventions for semantic versioning (you MUST still respect `disallowedChangeTypes`): |
| 128 | + |
| 129 | +- Use `"minor"` for breaking changes (do NOT use `"major"` unless specifically requested) |
| 130 | +- Use `"patch"` for any other changes that impact consumers of the package |
| 131 | +- Use `"none"` in the same circumstances as case 1 |
| 132 | + |
| 133 | +#### Case 3: Version IS prerelease |
| 134 | + |
| 135 | +ONLY if the package's current version includes a prerelease suffix, the typical options are `<prerelease|none>` (but you MUST respect `disallowedChangeTypes`): |
| 136 | + |
| 137 | +- `"prerelease"`: Any changes that impact consumers of the package |
| 138 | +- `"none"`: None of the changes will impact consumers of the package (e.g. the changes are only to non-exported test-specific files or documentation). If you're not certain, prefer `"prerelease"`. |
| 139 | +- There are additional options `premajor|preminor|prepatch`, but you should only use one of these if explicitly requested by the user or all other change types are disallowed. |
0 commit comments