Add tests, docs, change file; finalize lint/build/test

Copilot · web-flow · commit cca68bdbcba2 · 2026-04-29T09:36:42.000Z
Agent-Logs-Url: https://github.com/microsoft/beachball/sessions/dd2b3791-2992-450d-9f89-6b00c7ef6c81
diff --git a/PLAN.md b/PLAN.md
@@ -1,12 +1,12 @@
 # Implementation plan: rename `canary` → `prerelease`, simplify ChangeType
 
-This is a working document tracked alongside the implementation. It will be
-updated as discoveries are made or decisions change.
+This document tracked the plan as it was implemented.
 
 ## Decisions (open questions resolved)
 
-1. `prereleasePrefix` defaults to `"prerelease"` so `beachball prerelease` works
-   with zero configuration.
+1. `prereleasePrefix` defaults to `"prerelease"` (applied in the `prerelease`
+   command itself rather than in `getDefaultOptions`, to keep `configList`
+   output minimal). So `beachball prerelease` works with zero configuration.
 2. With `identifierBase: false` and the same target version already published,
    `beachball prerelease` errors with a message recommending `identifierBase: '0'`.
 
@@ -19,44 +19,65 @@ updated as discoveries are made or decisions change.
 - Shrink `ChangeType` to `'patch' | 'minor' | 'major' | 'none'`.
 - Migration: change files / CLI types `premajor|preminor|prepatch` are coerced
   to `major|minor|patch` with a warning; `prerelease` is a hard error.
-- `publish` strips an existing prerelease component from `package.json#version`
-  before applying the change file's bump (assumption E).
-- New `getPrereleaseVersion(...)` helper; `beachball prerelease` queries
+- `bump`/`publish` strip an existing prerelease component from
+  `package.json#version` before applying the change file's bump (assumption E).
+- New `getPrereleaseVersion(...)` pure helper; `beachball prerelease` queries
   `listPackageVersions` for the highest existing counter.
 
 ## Checklist
 
-- [ ] Explore the codebase to confirm exact file shapes/locations
-- [ ] Update `ChangeType` in `src/types/ChangeInfo.ts`
-- [ ] Migration logic for old types in `src/changefile/readChangeFiles.ts`
-      (warn + coerce `pre*`, error on `prerelease`)
-- [ ] CLI `--type` validation in `src/changefile/getPackageChangeTypes.ts`
-      (or wherever `--type` is parsed) — same coercion + error
-- [ ] `bumpPackageInfoVersion`: drop `prereleasePrefix`/`identifierBase` params,
+- [x] Update `ChangeType` in `src/types/ChangeInfo.ts`
+- [x] Migration logic for old types in `src/changefile/readChangeFiles.ts`
+      (warn + coerce `pre*`, error on `prerelease`); also handles
+      `dependentChangeType`
+- [x] CLI `--type` and `--dependent-change-type` migration in
+      `src/options/getCliOptions.ts` (same coercion + error)
+- [x] `bumpPackageInfoVersion`: drop `prereleasePrefix`/`identifierBase` params,
       strip prerelease component before `semver.inc` (handles assumption E)
-- [ ] New `src/bump/getPrereleaseVersion.ts` pure helper + unit tests
-- [ ] Rename `src/commands/canary.ts` → `src/commands/prerelease.ts`; rewrite
+- [x] New `src/bump/getPrereleaseVersion.ts` pure helper + unit tests
+- [x] Rename `src/commands/canary.ts` → `src/commands/prerelease.ts`; rewrite
       to use `listPackageVersions` + `getPrereleaseVersion`
-- [ ] `src/cli.ts`: replace `canary` case with `prerelease`
-- [ ] `src/types/BeachballOptions.ts`: drop `canaryName`; `command` includes
-      `prerelease` (and not `canary`)
-- [ ] `src/options/getCliOptions.ts`: drop `canaryName`; derive `tag` from
+- [x] `src/cli.ts`: replace `canary` case with `prerelease`
+- [x] `src/types/BeachballOptions.ts`: drop `canaryName`
+- [x] `src/options/getCliOptions.ts`: drop `canaryName`; derive `tag` from
       `prereleasePrefix` for the `prerelease` command
-- [ ] `src/options/getDefaultOptions.ts`: default `prereleasePrefix: 'prerelease'`,
-      drop `canaryName` default
-- [ ] `src/commands/configGet.ts`: drop `canaryName: true`
-- [ ] `src/help.ts`: replace `--canary-name` docs with `prerelease` section;
+- [x] `src/options/getDefaultOptions.ts`: drop `canaryName` default (default
+      for `prereleasePrefix` is applied at command level, not here)
+- [x] `src/commands/configGet.ts`: drop `canaryName: true`
+- [x] `src/help.ts`: replace `--canary-name` docs with `prerelease` section;
       remove `--prerelease-prefix` from `bump`/`publish` sections
-- [ ] `src/changefile/getQuestionsForPackage.ts`: drop "Prerelease" choice
-- [ ] Changelog rendering: drop `pre*`/`prerelease` `groupNames` entries; prune snapshots
-- [ ] Tests: update/remove canary references; add new tests per plan
-- [ ] Docs: rename `docs/cli/canary.md` → `docs/cli/prerelease.md`; update
-      sidebar; update `bump`/`publish` pages; update `configuration.md`,
-      `change-types.md`; sentence-case headings; build with `yarn docs:build`
-- [ ] Generate Beachball change file (major) via `/beachball-change-files`
-- [ ] Run `yarn build`, `yarn test`, `yarn lint`, `yarn format`
+- [x] `src/changefile/getQuestionsForPackage.ts`: drop "Prerelease" choice
+- [x] Changelog rendering: drop `pre*`/`prerelease` `groupNames` entries;
+      prune snapshot
+- [x] Update existing tests (configList snapshot, getCliOptions, bumpInMemory,
+      bumpPackageInfoVersion, changeTypes, getQuestionsForPackage,
+      updateRelatedChangeType, writeChangelog, e2e bump)
+- [x] Add new tests: - `__tests__/bump/getPrereleaseVersion.test.ts` - `__functional__/commands/prerelease.test.ts` - migration tests in `__functional__/changefile/readChangeFiles.test.ts` - legacy `--type` / `--dependent-change-type` tests in
+      `__functional__/options/getCliOptions.test.ts`
+- [x] Docs: create `docs/cli/prerelease.md`; add to sidebar in
+      `docs/.vuepress/config.ts`; remove `--prerelease-prefix` rows from
+      `docs/cli/bump.md` and `docs/cli/publish.md`; rewrite the
+      `prereleasePrefix` row in `docs/overview/configuration.md`; add
+      "Prereleases" section to `docs/concepts/change-types.md`. Built with
+      `yarn docs:build`.
+- [x] Generate Beachball change file (major)
+- [x] Run `yarn build`, `yarn test`, `yarn lint`
 - [ ] `parallel_validation`
 
 ## Notes/discoveries
 
-(to be filled in as work progresses)
+- The single repo fixture has only the package `foo`; tests use that name.
+- `createCommandContext` is `@deprecated` and triggers `etc/no-deprecated`;
+  command implementations and their tests use
+  `// eslint-disable-next-line etc/no-deprecated -- ...` to suppress.
+- `cliOptions.command === 'prerelease'` overrides `--tag`, mirroring previous
+  canary behavior. `--prerelease-prefix` outside of the `prerelease` command
+  does NOT affect tag.
+- `bumpInMemory.test.ts` previously had four `prereleasePrefix`-driven
+  scenarios; all are removed since `bump` no longer produces prereleases.
+  Replaced with a focused test for prerelease → release promotion.
+- `updateRelatedChangeType` tests previously expected `preminor` as a fallback
+  when `minor` was disallowed; with pre\* types removed, the algorithm now
+  falls back to `patch` instead.
+- `writeChangelog` "includes pre\* changes" tests are obsolete; replaced with
+  one test exercising `major`/`minor`/`patch` headers.
diff --git a/change/beachball-e78cf575-a41a-4ddb-a3ba-ff80340e848a.json b/change/beachball-e78cf575-a41a-4ddb-a3ba-ff80340e848a.json
@@ -0,0 +1,7 @@
+{
+  "packageName": "beachball",
+  "type": "major",
+  "dependentChangeType": "patch",
+  "comment": "Rename `canary` command to `prerelease`, repurpose `prereleasePrefix` (and remove `canaryName`), and shrink `ChangeType` to `patch | minor | major | none`. Old `pre*` change types in change files are auto-coerced (with a warning); `prerelease` change type is now an error. `bump`/`publish` no longer produce prerelease versions and now strip any prerelease component from the current version before bumping (prerelease → release promotion).",
+  "email": "198982749+Copilot@users.noreply.github.com"
+}
diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts
@@ -42,6 +42,7 @@ export default defineUserConfig({
           '/cli/change',
           '/cli/check',
           '/cli/config',
+          '/cli/prerelease',
           '/cli/publish',
           '/cli/sync',
         ],
diff --git a/docs/cli/bump.md b/docs/cli/bump.md
@@ -20,7 +20,6 @@ $ beachball bump
 
 [General options](./options) also apply for this command.
 
-| Option                | Description                                                                      |
-| --------------------- | -------------------------------------------------------------------------------- |
-| `--keep-change-files` | don't delete the change files from disk after bumping                            |
-| `--prerelease-prefix` | prerelease prefix (e.g. `beta`) for packages that will receive a prerelease bump |
+| Option                | Description                                           |
+| --------------------- | ----------------------------------------------------- |
+| `--keep-change-files` | don't delete the change files from disk after bumping |
diff --git a/docs/cli/prerelease.md b/docs/cli/prerelease.md
@@ -0,0 +1,55 @@
+---
+tags:
+  - cli
+category: doc
+---
+
+# `prerelease`
+
+Publishes a prerelease version (such as a canary, beta, or per-PR release) for the current change set, **without committing changes back to git or deleting change files**.
+
+```bash
+$ beachball prerelease
+```
+
+This command is useful for sharing prereleases of in-progress work — for example, a per-PR build that consumers can install to test changes before merging.
+
+## How it works
+
+For each package that has a change file (or that becomes modified due to dependency bumps), `beachball prerelease`:
+
+1. Looks up the change type from the change files (just like `bump` and `publish`).
+2. Computes the **target release version** by applying the change type to the current `package.json` version, after stripping any existing prerelease component. (For example, `0.2.0-beta.0` with a `minor` change type produces a target of `0.3.0`.)
+3. Queries the npm registry for existing published versions that match `<target>-<prereleasePrefix>.<n>`, finds the highest counter `N`, and publishes `<target>-<prereleasePrefix>.<N+1>`.
+4. Publishes to npm under the dist-tag matching `prereleasePrefix` (e.g. `beta`).
+
+If no matching prerelease versions have been published yet, the counter starts from [`identifierBase`](#options).
+
+The change files and `package.json` versions are **not** committed back to git. This means subsequent prerelease runs from the same change set will produce incrementing prerelease versions — useful for iterating on a PR without polluting git history.
+
+## Workflow example
+
+| Step | Command                                                          | Result                                                              |
+| ---- | ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| 1    | A developer creates a change file for a `minor` change to `foo`. | `change/foo-….json` exists; `foo` is at version `1.2.3`.            |
+| 2    | CI runs `beachball prerelease --prerelease-prefix pr30`.         | `foo@1.3.0-pr30.0` is published with dist-tag `pr30`.               |
+| 3    | The developer pushes another commit to the PR; CI re-runs.       | `foo@1.3.0-pr30.1` is published.                                    |
+| 4    | The PR is merged; main runs `beachball publish`.                 | `foo@1.3.0` is published with dist-tag `latest`, normal git commit. |
+
+Step 4 above demonstrates the **prerelease-to-release promotion** behavior of `bump`/`publish`: when a package's current `package.json` version contains a prerelease component (such as if `prerelease` ran on the same branch as `publish` would later run), the prerelease component is stripped before applying the bump, so the user gets the intuitive target release version.
+
+## Options
+
+[General options](./options) also apply for this command.
+
+<!-- prettier-ignore -->
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `--prerelease-prefix` | `'prerelease'` | Suffix used for the prerelease version, e.g. `"beta"` produces `1.2.3-beta.0`. The same value is used as the npm dist-tag. |
+| `--identifier-base` | `'0'` | Starting counter for prereleases when no matching versions are published yet. `'0'` (default) starts at `.0`, `'1'` starts at `.1`, or `false` omits the numeric counter entirely (in which case re-running on the same target version will error). |
+
+## Migrating from `beachball canary`
+
+This command replaces the old `beachball canary` command. The previous `canaryName` option has been removed; use `prereleasePrefix` instead.
+
+In addition, `bump` and `publish` no longer support producing prerelease versions directly. If you previously used `prereleasePrefix` with `bump`/`publish`, switch to `beachball prerelease` for prerelease publishing.
diff --git a/docs/cli/publish.md b/docs/cli/publish.md
@@ -19,7 +19,6 @@ Publishing automates all the bumping and synchronizing of package versions in th
 | `--git-tags`, `--no-git-tags` | | `true` (`--git-tags`) | whether to create git tags for published package versions |
 | `--keep-change-files` | | | don't delete the change files from disk after bumping |
 | `--message` | `-m` | `'applying package updates'` | custom commit message |
-| `--prerelease-prefix` | | | prerelease prefix (e.g. `beta`) for packages that will receive a prerelease bump |
 | `--publish`, `--no-publish` | | `true` (`--publish`) | whether to publish to the npm registry |
 | `--push`, `--no-push` | | `true` (`--push`) | whether to commit changes and push them back to the git remote |
 | `--registry` | `-r` | `'https://registry.npmjs.org'` | npm registry for publishing |
diff --git a/docs/concepts/change-types.md b/docs/concepts/change-types.md
@@ -38,6 +38,12 @@ Packages with a major version of 0 are considered unstable per the semver spec.
 
 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.
 
+## Prereleases
+
+To publish a prerelease version (such as a canary, beta, or per-PR build), use the [`beachball prerelease`](../cli/prerelease) command. There is no `prerelease` change type — instead, choose one of `patch`, `minor`, `major`, or `none` based on the impact of your changes, and let `beachball prerelease` handle the prerelease versioning.
+
+> **Note:** Older Beachball versions accepted `premajor`, `preminor`, `prepatch`, and `prerelease` as change types. These have been removed; existing change files using `premajor`/`preminor`/`prepatch` are auto-migrated to `major`/`minor`/`patch` (with a deprecation warning), and change files using `prerelease` will produce an error so they can be recreated with the appropriate type.
+
 ## Tips for reviewers
 
 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:
diff --git a/docs/overview/configuration.md b/docs/overview/configuration.md
@@ -93,7 +93,7 @@ For the latest full list of supported options, see `RepoOptions` [in this file](
 | `ignorePatterns` | `string[]` | | repo | Ignore changes in files matching these glob patterns ([see notes][6]) |
 | `npmReadConcurrency` | number | 5 | repo | Maximum concurrency for fetching package versions from the registry (see `concurrency` for write operations) |
 | `package` | `string` | | repo | Specifies which package the command relates to (overrides change detection based on `git diff`) |
-| `prereleasePrefix` | `string` | | repo | Prerelease prefix, e.g. `"beta"`. Note that if this is specified, packages with change type major/minor/patch will be bumped as prerelease instead. |
+| `prereleasePrefix` | `string` | `'prerelease'` | repo | Suffix used by the [`prerelease`](../cli/prerelease) command for prerelease versions, e.g. `"beta"` produces versions like `1.2.3-beta.0`. |
 | `packStyle` | `'sequential' \| 'layer'` | `'sequential'` | repo | With `packToPath`, how to organize the tgz files. `'sequential'` uses numeric prefixes to ensure topological ordering. `'layer'` groups the packages into numbered subfolders based on dependency tree layers. |
 | `packToPath` | `string` | | repo | Instead of publishing to npm, pack packages to tgz files under the specified path. |
 | `publish` | `boolean` | `true` | repo | Whether to publish to npm registry |
diff --git a/packages/beachball/src/__functional__/changefile/readChangeFiles.test.ts b/packages/beachball/src/__functional__/changefile/readChangeFiles.test.ts
@@ -188,6 +188,46 @@ describe('readChangeFiles', () => {
     expect(logs.mocks.warn).not.toHaveBeenCalled();
   });
 
+  it.each<['premajor' | 'preminor' | 'prepatch', 'major' | 'minor' | 'patch']>([
+    ['premajor', 'major'],
+    ['preminor', 'minor'],
+    ['prepatch', 'patch'],
+  ])('coerces legacy change type %s to %s with a warning', (legacyType, replacement) => {
+    tempRoot = createTestFileStructureType('monorepo');
+    const { options, packageInfos, scopedPackages } = getOptionsAndPackages();
+
+    generateChangeFiles([{ packageName: 'foo', type: legacyType as 'patch' }], options);
+    const changeSet = readChangeFiles(options, packageInfos, scopedPackages);
+
+    expect(changeSet).toHaveLength(1);
+    expect(changeSet[0].change.type).toBe(replacement);
+    expect(logs.mocks.warn).toHaveBeenCalledWith(
+      expect.stringContaining(`legacy change type "${legacyType}", which has been renamed to "${replacement}"`)
+    );
+  });
+
+  it('errors on legacy change type "prerelease"', () => {
+    tempRoot = createTestFileStructureType('monorepo');
+    const { options, packageInfos, scopedPackages } = getOptionsAndPackages();
+
+    generateChangeFiles([{ packageName: 'foo', type: 'prerelease' as 'patch' }], options);
+
+    expect(() => readChangeFiles(options, packageInfos, scopedPackages)).toThrow(
+      /change type "prerelease", which is no longer supported/
+    );
+  });
+
+  it('coerces legacy dependentChangeType "preminor" to "minor" with a warning', () => {
+    tempRoot = createTestFileStructureType('monorepo');
+    const { options, packageInfos, scopedPackages } = getOptionsAndPackages();
+
+    generateChangeFiles([{ packageName: 'foo', type: 'minor', dependentChangeType: 'preminor' as 'minor' }], options);
+    const changeSet = readChangeFiles(options, packageInfos, scopedPackages);
+
+    expect(changeSet[0].change.dependentChangeType).toBe('minor');
+    expect(logs.mocks.warn).toHaveBeenCalledWith(expect.stringContaining('legacy dependentChangeType "preminor"'));
+  });
+
   it('runs transform.changeFiles functions if provided', () => {
     const editedComment = 'Edited comment for testing';
     tempRoot = createTestFileStructureType('monorepo');
diff --git a/packages/beachball/src/__functional__/commands/prerelease.test.ts b/packages/beachball/src/__functional__/commands/prerelease.test.ts
diff --git a/packages/beachball/src/__functional__/options/getCliOptions.test.ts b/packages/beachball/src/__functional__/options/getCliOptions.test.ts
diff --git a/packages/beachball/src/__tests__/bump/getPrereleaseVersion.test.ts b/packages/beachball/src/__tests__/bump/getPrereleaseVersion.test.ts
diff --git a/packages/beachball/src/options/getCliOptions.ts b/packages/beachball/src/options/getCliOptions.ts
