You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .claude/skills/beachball-change-file/SKILL.md
+42-15Lines changed: 42 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
name: beachball-change-file
3
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.
@@ -16,10 +16,9 @@ Beachball normally uses a CLI with an interactive prompt to create change files,
16
16
- Check the root `package.json``scripts` for scripts that run `beachball change` and `beachball check`.
17
17
- The examples below assume `scripts` called `change` and `checkchange` respectively, but substitute the appropriate script names if found.
18
18
- 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)
19
-
- Check for the following settings in the beachball config (usually `beachball.config.js` or located in the root `package.json``beachball` key):
20
-
-`disallowedChangeTypes`: modifies the allowed `type` values in the change file
21
-
-`changeDir`: the default is `"change"`
22
-
-`branch`: target branch (usually `main` or `master` if not specified)
19
+
- Use `beachball config get` to check the following settings (this reads from the beachball config and returns the resolved value):
20
+
-`yarn beachball config get changeDir`: where to put the change files
21
+
-`yarn beachball config get branch`: target branch
23
22
24
23
## Creating a change file
25
24
@@ -90,16 +89,44 @@ Each grouped change file is located under `<changeDir>/change-<guid>.json`. It h
90
89
Each package's entry has the following values:
91
90
92
91
-`packageName`: The name of the changed package, e.g. `just-task`
93
-
-`type`: 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:
94
-
- If the package's current version does NOT have a prerelease suffix, choose `<patch|minor|major|none>` (omit any options banned by the beachball config's `disallowedChangeTypes` setting):
95
-
-**`"patch"`**: Bug fixes or other changes that don't impact exported API signatures.
96
-
-**`"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.)
97
-
-**`"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"`.
98
-
-**`"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"`.
99
-
- ONLY if the package's current version includes a prerelease suffix, choose `<prerelease|none>`:
100
-
-**`"prerelease"`**: Any changes that impact consumers of the package
101
-
-**`"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"`.
102
-
- If not certain about the change type, ask the user to choose one of the options above based on the diff content.
92
+
-`type`: The semantic versioning change type for the package. See "Determining the change type" below.
103
93
-`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).
104
94
-`comment` (`--message` CLI arg): A concise description of the changes made to the package. This will go in the changelog, so it should focus on user-facing changes rather than implementation details. This field accepts markdown formatting.
105
95
-`email`: User's email from `git config user.email`, or `"email not defined"` if not available. Do NOT invent an email.
96
+
97
+
#### Determining the change type
98
+
99
+
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.
100
+
101
+
If you're still uncertain about the change type after following the instructions below, ask the user to choose.
102
+
103
+
For each package, start by checking:
104
+
105
+
- The current `version` in `package.json`
106
+
-`disallowedChangeTypes` for the specific package: `yarn beachball config get disallowedChangeTypes --package <packageName>`
107
+
- 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.
108
+
109
+
##### Case 1: Version is 1.0.0 or greater and NOT prerelease
110
+
111
+
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`):
112
+
113
+
-**`"patch"`**: Bug fixes or other changes that don't impact exported API signatures.
114
+
-**`"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.)
115
+
-**`"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"`.
116
+
-**`"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"`.
117
+
- There are additional options `prerelease|premajor|preminor|prepatch`, but you should only use one of these if explicitly requested by the user.
118
+
119
+
##### Case 2: Version is 0.x.y and NOT prerelease
120
+
121
+
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:
122
+
123
+
- Use **`"minor"`** for breaking changes (no need to confirm with the user)
124
+
- Use **`"patch"`** for any other changes that impact consumers of the package
125
+
126
+
##### Case 3: Version IS prerelease
127
+
128
+
ONLY if the package's current version includes a prerelease suffix, the typical options are `<prerelease|none>` (but you MUST respect `disallowedChangeTypes`):
129
+
130
+
-**`"prerelease"`**: Any changes that impact consumers of the package
131
+
-**`"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"`.
132
+
- 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.
-**E2E** (`src/__e2e__/`): E2E tests covering major scenarios and entire commands
74
74
75
75
Test helpers in `src/__fixtures__/` provide mock factories for repos, logs, package infos, and change files.
76
+
77
+
### Test writing tips
78
+
79
+
- Avoid manually creating complex object structures (such as `PackageInfos`, `ChangeInfo`, `BumpInfo`, or `BeachballOptions`). Consider one of the following approaches instead:
80
+
- call the real function for generating the structure if possible
81
+
- check if there's a helper under `__fixtures__`
82
+
- check for a common pattern for creating/mocking this object in other tests
83
+
- When testing a function with complex parameters, consider creating a wrapper function in the test which fills in common defaults.
84
+
- Any test of a function which writes to the console should call `initMockLogs()` to mock and capture output.
85
+
- Beachball's logs are its UI. Often, tests should include complete inline snapshots of output (especially if it's only a few lines).
86
+
- Where reasonable, prefer complete tests of values: `expect(someObj).toEqual({...})` rather than `expect(someObj.foo).toEqual(...)` or `expect(someObj).toMatchObject({...})`, or `expect(someArray).toEqual([...])` rather than `expect(someArray).toContain(...)`
inspect the effective beachball configuration for the repo or a specific package
40
+
37
41
## Options
38
42
39
43
Some of the most common options are summarized below. **For all options, see the pages for [CLI options](https://microsoft.github.io/beachball/cli/options.html) and [config file options](https://microsoft.github.io/beachball/overview/configuration.html).**
|`--all`|| false | Generate change files for all packages |
24
-
|`--dependent-change-type`||`patch`| use this change type for dependent packages |
25
23
|`--message`|`-m`| (prompt) | Description for all change files |
26
-
|`--no-commit`|| false | Stage the change files rather than committing |
27
-
|`--package`|| (changed packages) | Generate change files for these packages (can be specified multiple times) |
28
24
|`--type`|| (prompt) | Type for all the change files (must be valid for each package) |
25
+
|`--package`|| (changed packages) | Generate change files for these packages (can be specified multiple times) |
26
+
|`--all`|| false | Generate change files for all packages, even without detected changes |
27
+
|`--dependent-change-type`||`patch`| Use this change type for dependent packages (rarely modified) |
28
+
|`--no-commit`|| false | Stage the change files rather than committing |
29
29
30
30
### Examples
31
31
@@ -76,7 +76,7 @@ Found changes in the following packages:
76
76
some-pkg
77
77
```
78
78
79
-
For each package, the prompt will start by asking for a change **type**. This should be chosen based on [semantic versioning rules](https://semver.org/) because it determines how to update the package version. If the change doesn't affect the published package at all (e.g. you just updated some comments), choose `none`.
79
+
For each package, the prompt will start by asking for a change **type**. This should be chosen based on [semantic versioning](../concepts/change-types) because it determines how to update the package version. If the change doesn't affect the published package at all (e.g. you just updated some comments), choose `none`.
Inspect the effective beachball configuration. This is mainly useful if you'd like to see all the config values and defaults, or for AI agents to determine the effective setting value for a specific package.
10
+
11
+
The `config` command has two subcommands: `get` and `list`. (There's no plan to add a `set` command since the config file is usually JS.)
12
+
13
+
## `config get <name>`
14
+
15
+
Get the value of a specific config setting. If the setting can be overridden per-package or per-group, any overrides are also shown.
16
+
17
+
```bash
18
+
$ beachball config get branch
19
+
# "origin/main"
20
+
21
+
$ beachball config get disallowedChangeTypes
22
+
# Main value: null
23
+
24
+
# Group overrides:
25
+
# my-group:
26
+
# disallowedChangeTypes: ["major"]
27
+
# packageNames: ["pkg-a", "pkg-b"]
28
+
```
29
+
30
+
### Options
31
+
32
+
#### `--package, -p`
33
+
34
+
Get the effective value of the setting for specific package(s). For settings like `disallowedChangeTypes`, this accounts for group membership and package-level overrides.
35
+
36
+
Can be specified multiple times.
37
+
38
+
```bash
39
+
$ beachball config get disallowedChangeTypes --package pkg-a
40
+
# pkg-a: ["major"]
41
+
42
+
$ beachball config get tag --package pkg-a --package pkg-b
43
+
# pkg-a: "beta"
44
+
# pkg-b: "latest"
45
+
```
46
+
47
+
## `config list`
48
+
49
+
List all config settings (including defaults), plus any group and per-package overrides.
50
+
51
+
The formatting is similar to YAML, but is not currently intended to be parsed (keys are not quoted).
Copy file name to clipboardExpand all lines: docs/concepts/change-files.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -49,7 +49,7 @@ $ yarn change
49
49
If you don't already have a change file for this branch and package, it will ask you to enter a description and a change type (in a monorepo, it will ask for each changed package).
50
50
51
51
- For the **description**, `beachball` will provide a list of recent commit messages to choose from, or you can type a custom message.
52
-
- Choose the correct **type**using [semantic versioning rules](https://semver.org/).
52
+
- Choose the correct **type**based on the impact of your changes. See [change types](./change-types) for guidance.
53
53
54
54
After you've answered those questions, a change file similar to the example above is created and committed in your branch under `/change`.
When running [`beachball change`](../cli/change), you need to choose a **change type** that describes the impact of your changes. Beachball uses this to determine how to bump the package version.
10
+
11
+
The available types follow [semantic versioning](https://semver.org/) conventions.
12
+
13
+
## Choosing a change type
14
+
15
+
### Stable packages (version >= 1.0.0)
16
+
17
+
<!-- prettier-ignore -->
18
+
| Type | When to use | Version bump |
19
+
| ---- | ----------- | ------------ |
20
+
|`patch`| Bug fixes or internal changes that don't affect exported API signatures | 1.0.0 → 1.0.1 |
21
+
|`minor`| New exported APIs, non-breaking changes to exported API signatures, or significant changes to internal logic | 1.0.0 → 1.1.0 |
22
+
|`major`| Breaking changes to exported APIs (removals or breaking signature changes), critical dependency updates, or behavior changes that could break consumers | 1.0.0 → 2.0.0 |
23
+
|`none`| Changes that don't affect consumers at all (tests, documentation, internal config) | no bump |
24
+
25
+
When in doubt between `minor`/`patch` or `patch`/`none`, it's generally best to choose the larger change type.
26
+
27
+
### Zero-version packages (version 0.x.y)
28
+
29
+
Packages with a major version of 0 are considered unstable per the semver spec. The conventions are slightly different:
|`patch`| Any non-breaking changes that affect consumers | 0.1.0 → 0.1.1 |
34
+
|`minor`| Breaking changes | 0.1.0 → 0.2.0 |
35
+
|`none`| Changes that don't affect consumers at all | no bump |
36
+
37
+
## Disallowed change types
38
+
39
+
Some repos or packages may restrict which change types are allowed using the [`disallowedChangeTypes`](../overview/configuration#options) config option. For example, `major` bumps are often disallowed to ensure coordination of major release efforts. Any disallowed options will be omitted from the interactive prompt, and a change file or `--type` argument that uses a disallowed type will cause an error.
40
+
41
+
## Tips for reviewers
42
+
43
+
Change files show up as part of the PR diff, making it easy to verify the change type during code review. Common things to watch for:
44
+
45
+
- A `patch` that should be `minor` because a new API was added
46
+
- A `minor` that should be `major` because an existing API was changed in a breaking way
47
+
- A `none` that should be `patch` because the change does affect published output
0 commit comments