Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ concurrency:

jobs:
check:
if: github.event_name != 'pull_request' || !github.event.pull_request.draft
name: check
runs-on: ubuntu-latest
timeout-minutes: 20
Expand Down
21 changes: 20 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Small typo corrections, narrow documentation fixes, and repository metadata upda
# Aggregate gate: format:check, build, lint, typecheck, test, repository checks:
npm run check

# Change files for package changes (compares with origin/main; CI runs it on every PR):
# Change files for package changes (compares with origin/main; CI runs it on Ready PRs):
npm run change:verify

# PR/MR title:
Expand All @@ -72,6 +72,25 @@ gh repo-checks protect --repo OWNER/REPO
npm run publish:dry-run
```

## CI Execution Policy

The full `CI` workflow runs for Ready PRs when they are opened, updated with new commits (`synchronize`),
reopened, or changed from Draft to Ready. Its `check` job skips Draft PR events; the existing `push` to `main`
trigger still runs the full checks. This follows the [base template's CI policy](https://github.com/PerfectPan/project-template/pull/9)
without replacing the Rush setup, validation commands or release workflows. Preserve any existing necessary
manual triggers when applying this policy to a downstream project.

Keep work in Draft until local checks are finished. A skipped job reports success to GitHub, including required
checks, but is not test evidence. Mark the PR Ready and confirm that `check` actually executed and passed for
the current head and merge result before merging. Version Packages continues to return release PRs to Draft
on each update, so a maintainer reviews them and marks them Ready again.

The separate `Review` workflow only checks repository hygiene, title and description. It remains active on
Draft PRs and metadata edits; Bot authors skip only the description check. Full CI does not run for metadata
edits. After a base-only change, update the comparison and request a fresh PR run by updating the branch or
selecting Draft then Ready. Preserve existing required check names when adopting the policy; workflow files
do not configure branch protection or rulesets.

## Change Files

Rush builds changelogs and version bumps from change files in `common/changes/`. A PR that changes what a
Expand Down
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,12 @@ The root `package.json` is not a Rush project. Its scripts call `common/scripts/

## CI and Releases

- `ci.yml` runs `npm run check` on pull requests and `main`, and on pull requests also requires Rush change files
for package changes. It caches Rush's pnpm store and npm cache, keyed by the lockfile. Private repositories pay for
Actions minutes: there, consider running CI only on `ready_for_review` plus `workflow_dispatch` instead of every push.
- `review.yml` (from the upstream template) checks repository hygiene, the PR title and the PR description.
- `ci.yml` runs `npm run check` on Ready PR creation, new commits, reopening and Draft-to-Ready transitions, and
keeps the existing `main` push checks. Draft PR events skip the full job; keep unfinished work in Draft to avoid
full runs before it is ready. PR checks also require Rush change files for package changes. Dependency downloads
are cached using the lockfile. See [CI Execution Policy](CONTRIBUTING.md#ci-execution-policy).
- `review.yml` (from the upstream template) checks repository hygiene, the PR title and the PR description,
including during Draft work and metadata edits.
- `version-packages.yml` (manual) opens the draft PR `chore(release): version packages`.
- `publish-npm.yml` publishes when a non-prerelease GitHub Release is published.
- Dependabot updates npm dependencies and GitHub Actions weekly with `chore(deps)` titles.
Expand Down
23 changes: 13 additions & 10 deletions docs/development/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,18 +75,20 @@ authentication error for that package only.
## Cutting a Release

1. Merge feature PRs with change files (`npm run change`). CI runs `rush change --verify` and
`scripts/release-intent.ts check` on every PR except the release PR and Dependabot PRs.
`scripts/release-intent.ts check` on Ready PRs except the release PR and Dependabot PRs.
2. Run **Actions → Version Packages → Run workflow** on `main`. Choose `policy` for the policy's `nextBump`, or
`patch`/`minor`/`major`. The workflow runs `rush version --bump`, which consumes the change files, bumps the
policy and package versions and writes changelogs, then `rush update`, and opens or updates the signed draft PR
`chore(release): version packages` from `rush-release/main`. The PR body is the output of
`scripts/release-notes.ts`: the fixed intro followed by each policy package's `## <name>@<version>` section from
its `CHANGELOG.md`. The script cuts the body at a package boundary and points at the CHANGELOG files before
create-pull-request would truncate it mid-section at GitHub's 65,536-character limit.
3. Start CI on the release PR. Pull requests created with the workflow's `GITHUB_TOKEN` do not trigger workflows.
Select **Ready for review** (the `ready_for_review` event starts CI), or close and reopen the PR. Pushing an
empty commit to the branch also works. To avoid the manual step, give `create-pull-request` a GitHub App token
or a fine-grained PAT instead of `GITHUB_TOKEN`.
3. Review the Draft release PR, then select **Ready for review** to start the full `check` job. Later commits
on a Ready PR also run CI, but Version Packages returns the PR to Draft on each update, so a maintainer must
mark it Ready again. Reopening or pushing a commit while it is still Draft does not execute full CI.
GitHub may require approval for runs from PRs created or updated with `GITHUB_TOKEN`; approve the requested
run when needed ([current GitHub behavior](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow)).
This flow keeps the existing token and permissions. A skipped Draft job is not a passing test run.
4. Review the version and changelog diff, wait for green checks, and squash-merge.
5. Check the release identity locally on the merged release commit:

Expand Down Expand Up @@ -151,9 +153,10 @@ and changes nothing.
and blocks the version number permanently; prefer deprecation.
- Once any package of a version is on npm, do not move or reuse its tag. Fix forward with a new version.

## CI Trigger Options
## CI Trigger Policy

`ci.yml` runs on ordinary `pull_request` and `push` events, which is enough for a single-maintainer repository. A
repository that wants CI to validate an exact head/base pair, or to skip CI on drafts, can replace it with a
`workflow_dispatch` workflow that takes `head_sha`/`base_sha` inputs and re-checks the PR head before and after the
run. That design costs a manual trigger per PR; adopt it only when stale or racing CI results are a real problem.
`ci.yml` listens to PR creation, new commits, reopening and Ready transitions. Its full `check` job runs only
when the PR event is non-Draft; main pushes retain their existing full check run. Lightweight `Review` checks
continue during Draft work and metadata edits. Neither workflow change grants permissions or publishes a
package. See [CI Execution Policy](../../CONTRIBUTING.md#ci-execution-policy) for the shared policy and the
requirement to inspect an actually executed check for the current PR comparison before merging.
Loading