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.
Use this guide when shipping changes in the FAST monorepo — writing PR descriptions, generating change files, and keeping documentation up to date.
Do NOT perform any of the following actions autonomously. These require explicit human action:
git push, git push --force, or any remote push operations.gh pr create, or MCP tools that create PRs.gh issue create, issue comments, or label changes.gh pr merge, gh pr close, or equivalent.npm publish, beachball publish, or release operations.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.
Read these documents for additional context when needed:
.github/pull_request_template.md — PR description template (source of truth for PR structure).CONTRIBUTING.md — Full contributor guide (machine setup, branching, governance).BRANCH_GUIDE.md — Branch management conventions.beachball.config.js — Beachball configuration (ignored patterns, publish settings).CODE_OF_CONDUCT.md — Community standards.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.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 fast-html parserfix: resolve memory leak in template bindingchore: update dev dependenciesUse 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.
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".
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.
The reviewer notes section is optional. Include it only if there are specific areas where you would like feedback or attention from the reviewer.
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".
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.
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.
Before finishing any change, run these commands from the monorepo root and confirm they pass:
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
After completing a change to any package under packages/, generate a Beachball change file:
# 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.
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) |
The Beachball config (beachball.config.js) ignores these paths — changes limited to them do not need change files:
.github/ — CI configs, templates, skillssrc/e2e/, src/tests/, src/fixtures/)package-lock.json.vscode/, .prettierrcWhen working across feature branches, target the branch explicitly:
npm run change -- --branch origin/{branch-name}
If addressing multiple unrelated issues, prefer separate pull requests.
When introducing breaking changes:
major as the change type when running npm run change.packages/<package>/MIGRATION.md.Format for MIGRATION.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 first.
Keep the website documentation in sites/website/src/docs/ updated when making changes that affect public APIs, behavior, or usage patterns. The documentation is organized by version:
sites/website/src/docs/2.x/ — Current version documentation (getting started, guides, advanced topics, API reference).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.