| description | Use this skill when contributing changes to the FAST monorepo — creating pull requests, generating change files, writing PR descriptions, and keeping documentation up to date. |
| name | shipping |
Shipping Patterns for FAST
Use this guide when shipping changes in the FAST monorepo — writing PR descriptions, generating change files, and keeping documentation up to date.
Guardrails
Do NOT perform any of the following actions autonomously. These require explicit human action:
- Do not push branches — no
git push, git push --force, or any remote push operations.
- Do not create pull requests — no GitHub API calls,
gh pr create, or MCP tools that create PRs.
- Do not create or modify GitHub issues — no
gh issue create, issue comments, or label changes.
- Do not merge or close pull requests — no
gh pr merge, gh pr close, or equivalent.
- Do not publish packages — no
npm publish, beachball publish, or release operations.
- Do not modify branch protection or repository settings.
You may prepare all of these (e.g., draft a PR description, generate change files, stage commits) but the human must execute the final action.
Key references
Read these documents for additional context when needed:
Package/Crate references
Read these documents, they are located at the root of the specific package or crate, e.g. packages/<package>/<file>.md and relate to the package/crates they are located in. When making changes in the package/crate afterwards update these files if necessary.
DESIGN.md - Explains the code patterns.README.md - Explains how a developer/agent would use this package/crate.
Commit and PR title conventions
Use conventional commit format for PR titles and merge commit messages:
<type>: <short summary>
Common types: feat, fix, chore, docs, refactor, test, perf.
Examples:
feat: add shadow DOM support to declarative templatesfix: resolve memory leak in template bindingchore: update dev dependencies
Pull requests
Use the repository's PR template at .github/pull_request_template.md as the basis for all pull request descriptions.
Provide the markdown code block only, without any additional commentary or explanation.
The comments in the template can be removed since they're only meant to provide guidance on how to fill out the template, and are not intended to be part of the final PR description.
Fill out each section as detailed below.
Description
The Description should be either a summary description of the content of the branch,
or a list of the most relevant changes made in the branch. The goal is to address
the purpose of the pull request in a concise manner, rather than detailing every change. "Why"
and "what" over "how".
Issues
Determine if any current github issues are being addressed by this work, and
list them in the Issues section with links. If none are found, remove the Issues section.
Reviewer Notes
The reviewer notes section is optional. Include it only if there are specific
areas where you would like feedback or attention from the reviewer.
Test Plan
The Test Plan section should outline any issues that need to be verified before merging,
or steps to reproduce the behavior locally. Even a brief note is helpful, such as "All existing tests pass".
Checklist
The checklist section should be completed to indicate the status of various
aspects of the pull request.
If there are change files that have been added to the PR, check the box labeled "I have included a change request file using $ npm run change".
If any new tests have been added, check the box labeled "I have added tests for my changes."
Check the terminal output for evidence of passing tests, and check the box labeled "I have tested my changes." if tests have been run and are passing. If not, leave the box unchecked.
If any doc blocks have been added or modified, or if any documentation files have been added or modified, check the box labeled "I have updated the project documentation to reflect my changes." This also applies to any changes made to api-report files.
The final checkbox must be checked by the pull request author. It should never be checked when generating this PR description.
Next Steps
The Next Steps section is optional. Include it only if there are specific follow-up tasks
or work items that should be addressed after merging this PR, such as updating documentation, adding new tests, or performing code cleanup. If any existing issues are being addressed by the next steps, reference them here.
Acceptance checklist
Before making a change, if the change is addressing a bug make sure you write a test first and ensure that it is failing:
npm run build
npm run test
Before finishing any change, run these commands from the monorepo root and confirm they pass:
npm run build
npm run test
npm run format:check
npm run checkchange
Change files
After completing a change to any package under packages/, generate a Beachball change file:
npm run change
This walks through the steps to create a change description file that is required for versioning and publishing. The CI gate npm run checkchange will fail if a change file is missing for a modified package.
Change comments
Write the comment field as release-note text, not as a commit message. Use a
concise sentence that starts with a capital letter and ends with a period. Do not
prefix comments with conventional commit types such as fix:, feat:, or
chore:.
Beachball uses change-file comments to generate package changelogs and release
notes. Sentence-style comments read cleanly in those user-facing outputs, while
commit-style prefixes duplicate the separate change type metadata and add noise.
Change types
When prompted, select the appropriate change type:
| Type | When to use |
|---|
major | Breaking changes to public API |
minor | New features, non-breaking additions |
patch | Bug fixes, minor corrections |
none | Changes that don't affect the published package (tests, docs, tooling) |
When change files are NOT required
The Beachball config (beachball.config.js) ignores these paths — changes limited to them do not need change files:
.github/ — CI configs, templates, skills- Test files (
src/e2e/, src/tests/, src/fixtures/)
package-lock.json.vscode/, .prettierrc
Additionally, build/scripts/checkchange.mjs (which wraps beachball check for the checkchange npm script) skips the check entirely on manual version bump branches authored by a repo admin. Specifically, both of the following must be true for the current run:
- Branch name matches
^publish_\d+$ (beachball's documented publish-branch convention).
- The actor (
$GITHUB_ACTOR in CI; locally, the user from gh api user) has the admin role on microsoft/fast, verified via the GitHub REST API.
If either condition fails, the change-file requirement applies as before. See CONTRIBUTING.md > Manual version bumps for the full rationale and reviewer expectations.
Cross-branch targeting
When working across feature branches, target the branch explicitly:
npm run change -- --branch origin/{branch-name}
Multiple unrelated changes
If addressing multiple unrelated issues, prefer separate pull requests.
Breaking changes
When introducing breaking changes:
- Select
major as the change type when running npm run change.
- Document the migration strategy in
packages/<package>/docs/migration/<migration-name>.md.
Format for a migration document:
# Migrating from previous versions
## v1 to v2
- Export `Foo` has been renamed to `Bar`.
- `Bat` has been updated to use the new API [`BatConfig`](link/to/api).
If the breaking change is significant or requires multiple PRs, open a discussion first.
Documentation
After any changes ensure that the documentation is up to date, this includes the files DESIGN.md and README.md files for any packages/crates that have been modified. If your changes update or add to the public API, update the sites/website/src/docs/ files. Only update the latest version, these are denoted by major versions in their folder names inside the docs folder, 1.x, 2.x, etc., find the latest version of the docs and modify them if necessary.
When adding or modifying exported APIs, run the website prebuild script to regenerate API documentation from the api-extractor output:
npm run prebuild -w sites/website
This runs sites/website/scripts/generate-docs.cjs, which copies API documentation from each package's extracted API reports into the website source. Run this after building packages to ensure generated documentation stays in sync with the codebase.
