# Shipping > 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. - Skill: `microsoft/shipping` (Agent Skill) - Install (CLI): `npx skillmds@latest add microsoft/shipping` - Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/shipping/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: Microsoft (https://skillmd.com/u/microsoft) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/microsoft/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: - [`.github/pull_request_template.md`](../../pull_request_template.md) — PR description template (source of truth for PR structure). - [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — Full contributor guide (machine setup, branching, governance). - [`BRANCH_GUIDE.md`](../../../BRANCH_GUIDE.md) — Branch management conventions. - [`beachball.config.js`](../../../beachball.config.js) — Beachball configuration (ignored patterns, publish settings). - [`CODE_OF_CONDUCT.md`](../../../CODE_OF_CONDUCT.md) — Community standards. ### Package/Crate references Read these documents, they are located at the root of the specific package or crate, e.g. `packages//.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](https://www.conventionalcommits.org/) format for PR titles and merge commit messages: ``` : ``` Common types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`. Examples: - `feat: add shadow DOM support to declarative templates` - `fix: resolve memory leak in template binding` - `chore: update dev dependencies` # Pull requests Use the repository's PR template at [`.github/pull_request_template.md`](../../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: ```bash npm run build # all packages build successfully npm run test # test fails ``` Before finishing any change, run these commands from the monorepo root and confirm they pass: ```bash npm run build # all packages build successfully npm run test # all tests pass npm run format:check # Prettier formatting is correct npm run checkchange # Beachball change files exist for packages/* changes ``` # Change files After completing a change to any package under `packages/`, generate a Beachball change file: ```bash # This should be run from the monorepo root 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`](../../../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`](../../../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: 1. Branch name matches `^publish_\d+$` (beachball's documented publish-branch convention). 2. 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](../../../CONTRIBUTING.md#manual-version-bumps) for the full rationale and reviewer expectations. ## Cross-branch targeting When working across feature branches, target the branch explicitly: ```bash 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: 1. Select `major` as the change type when running `npm run change`. 2. Document the migration strategy in `packages//docs/migration/.md`. Format for a migration document: ```md # 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](https://github.com/microsoft/fast/discussions) 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: ```bash npm run prebuild -w sites/website ``` This runs [`sites/website/scripts/generate-docs.cjs`](../../../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.