agentleFS
MicrosoftKnown publishermicrosoft/lage/.agents/skills/beachball-change-file/SKILL.md

beachball-change-file

Skill817 starsChanged 4 months agoMITView on GitHub

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.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 1

    1. microsoft/just★ 2k100% same

    Edited · 0

    None found.

    Wrote their own version · 1

    1. microsoft/beachball★ 816same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 4 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Check the root package.json scripts for scripts that run beachball change and beachball check.

    line 22
  2. Very specific:

    Use beachball config get to check the following settings (note: beachball config get only exists in versions >= 2.64.0)

    line 25
  3. Distinctive:

    If there are any unstaged or untracked changes, ask the user whether they would like to stage all files or continue without staging.

    line 39
  4. Very specific:

    Run yarn checkchange --verbose to get the list of changed packages and files considered by beachball:

    line 43
  5. Distinctive:

    DO NOT manually check for existing change files.

    line 48
  6. Distinctive:

    When checking diffs to generate change files, DO NOT merge with the target branch.

    line 54
  7. Very specific:

    If groupChanges is false or unset, you should create a separate change file for each package.

    line 58
  8. Very specific:

    Create a change file under <changeDir>/<packageName>-<guid>.json with the following format.

    line 63
  9. Very specific:

    If groupChanges is true, you should create a single change file.

    line 77
  10. Very specific:

    Create a single change file under <changeDir>/change-<guid>.json with the following format.

    line 80
  11. Very specific:

    Run git add <changeDir>, then re-run yarn checkchange to verify.

    line 98
  12. Distinctive:

    If you're still uncertain about the change type after following the instructions below, ask the user to choose.

    line 116
  13. Very specific:

    If the package's current version is 1.0.0 or greater and does NOT have a prerelease suffix, the typical options are …

    line 126
  14. Very specific:

    If the package's major version is 0 and does NOT have a prerelease suffix, this is similar to case 1.

    line 136
  15. Very specific:

    Use "minor" for breaking changes (do NOT use "major" unless specifically requested)

    line 138
  16. Very specific:

    Use "patch" for any other changes that impact consumers of the package

    line 139
  17. Very specific:

    Use "none" in the same circumstances as case 1

    line 140
  18. Very specific:

    ONLY if the package's current version includes a prerelease suffix, the typical options are <prerelease|none> (but you MUST respect …

    line 144

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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.

Prerequisites

  • Determine 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.)
  • 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.
  • Check the root package.json scripts for scripts that run beachball change and beachball check.
    • The examples below assume scripts called change and checkchange respectively, but substitute the appropriate script names if found.
    • 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)
  • Use beachball config get to check the following settings (note: beachball config get only exists in versions >= 2.64.0)
    • yarn beachball config get changeDir: where to put the change files
    • yarn beachball config get branch: target branch name
    • yarn beachball config get groupChanges: whether grouped change files are enabled (true/false/undefined)

Creating and validating a change file

Usually, an AI agent should create a change file manually following the standardized format detailed below.

1. Validate repo state

Beachball only considers staged and committed files, so you should check for unstaged or untracked changes before proceeding:

  1. Get file paths with unstaged changes (git ls-files -m) and untracked changes (git ls-files -o --exclude-standard)
  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.

2. Get changed packages

Run yarn checkchange --verbose to get the list of changed packages and files considered by beachball:

  • 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)
  • The list of changed files is under "changed files in current branch". IGNORE any files with ~~ strikethrough formatting.

DO NOT manually check for existing change files.

3. Create the change file(s)

Change files are located under <changeDir>. There are two possible structures for change files, determined by the groupChanges setting.

When checking diffs to generate change files, DO NOT merge with the target branch; just use the local merge-base.

Case 1: Non-grouped format (groupChanges is false or unset)

If groupChanges is false or unset, you should create a separate change file for each package.

For each changed package as listed by beachball:

  1. Generate a random GUID: node -e "console.log(crypto.randomUUID())"
  2. Create a change file under <changeDir>/<packageName>-<guid>.json with the following format. See Change entry values below for the proper values of each field.
{
  "packageName": "",
  "type": "",
  "dependentChangeType": "",
  "comment": "",
  "email": ""
}

Case 2: Grouped format (groupChanges: true)

If groupChanges is true, you should create a single change file.

  1. Generate a random GUID: node -e "console.log(crypto.randomUUID())"
  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 below for the proper values of each field.
{
  "changes": [
    {
      "packageName": "",
      "type": "",
      "dependentChangeType": "",
      "comment": "",
      "email": ""
    }
  ]
}

4. Validate the change file(s)

Run git add <changeDir>, then re-run yarn checkchange to verify.

Change entry values

Each package's entry has the following values:

  • packageName: The name of the changed package, e.g. just-task
  • type: The semantic versioning change type for the package. See Determining a package's change type below.
  • 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).
  • comment (--message CLI arg): A concise description of the changes made to the package. Tips:
    • This will go in the changelog, so it should focus on user-facing changes (especially any API changes) rather than implementation details.
    • Markdown formatting is allowed, so any references to names from code should be wrapped with backticks.
  • email: User's email from git config user.email, or "email not defined" if not available. Do NOT invent an email.

Determining a package's change type

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.

If you're still uncertain about the change type after following the instructions below, ask the user to choose.

For each package, start by checking:

  • The current version in package.json
  • disallowedChangeTypes for the specific package: yarn beachball config get disallowedChangeTypes --package <packageName>
  • 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.

Case 1: Version is 1.0.0 or greater and NOT prerelease

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):

  • "patch": Bug fixes or other changes that don't impact exported API signatures.
  • "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.)
  • "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".
  • "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".
  • There are additional options prerelease|premajor|preminor|prepatch, but you should only use one of these if explicitly requested by the user.

Case 2: Version is 0.x.y and NOT prerelease

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):

  • Use "minor" for breaking changes (do NOT use "major" unless specifically requested)
  • Use "patch" for any other changes that impact consumers of the package
  • Use "none" in the same circumstances as case 1

Case 3: Version IS prerelease

ONLY if the package's current version includes a prerelease suffix, the typical options are <prerelease|none> (but you MUST respect disallowedChangeTypes):

  • "prerelease": Any changes that impact consumers of the package
  • "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".
  • 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.