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
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ name: CI

on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
push:
branches:
- main
Expand All @@ -11,6 +12,7 @@ permissions:

jobs:
test:
if: github.event_name != 'pull_request' || !github.event.pull_request.draft
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
Expand Down
8 changes: 3 additions & 5 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,9 @@ jobs:

- run: pnpm typecheck

# The release PR is opened with GITHUB_TOKEN, and GitHub does not start
# workflows for events that token causes, so CI does not run on it by
# itself. Before merging, close and reopen the PR (or push an empty commit
# to its branch) as a person: `gh pr close <n> && gh pr reopen <n>`.
# A `gh workflow run` dispatch is not attached to the PR and does not count.
# GITHUB_TOKEN-created PR events can require a maintainer to approve workflow runs.
# This release flow does not force Draft. If the PR is Draft, mark it Ready
# before expecting full CI; verify that test actually ran and passed, not skipped.
- name: Create release pull request
id: changesets
uses: changesets/action@v2
Expand Down
26 changes: 24 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Small fixes, typo corrections, dependency metadata updates, and narrow documenta

## Required Checks

CI (`.github/workflows/ci.yml` and `.github/workflows/review.yml`) runs these on every pull request; run them locally before opening review:
Run these checks locally before requesting review. The full CI and lightweight Review workflows follow the [CI Execution Policy](#ci-execution-policy) below:

```bash
# Repository checks:
Expand Down Expand Up @@ -70,6 +70,28 @@ Upgrade the shared rules by bumping the tag in `package.json`, then fix or expli

For package-facing changes, also run `pnpm changeset status` and the `npm pack --dry-run` check in [Pull Request Expectations](#pull-request-expectations).

## CI Execution Policy

The full `test` job in `.github/workflows/ci.yml` runs for Ready PRs when they are opened, updated with new
commits (`synchronize`), reopened, or changed from Draft to Ready. The job skips Draft PR events. The existing
push-to-`main` trigger is preserved; the Draft condition applies only to pull requests. No manual CI trigger is
added.

Keep work in Draft until local checks are finished. GitHub reports a skipped job as successful, even when it is
required by branch protection; this is not evidence that tests ran. After marking a PR Ready, confirm the full
`test` job actually executed and passed for the current head and merge result before merging. A base-only
change needs a refreshed branch or another Draft-to-Ready transition to validate the new comparison.

The separate `Review` workflow stays active on Draft PRs and metadata edits. Its repository hygiene, title and
description checks do not install dependencies or run the full test suite, so authors get early feedback while
Drafts save full-CI usage. Bot authors remain exempt only from the description check. Metadata-only edits run
Review without repeating full CI.

Release PRs keep their existing creation behavior; this change does not force them into Draft or change
publishing. Follow [Releasing](#releasing) if GitHub requires workflow approval. Repository settings are separate:
preserve check names and inspect the actual merge requirements in [Repository Setup](#repository-setup), and
never use a skipped full-CI check as proof that a Ready PR is safe to merge.

## Changesets

Use Changesets for package version and changelog entries:
Expand All @@ -85,7 +107,7 @@ Only published packages get changesets. Private workspace packages (`private: tr
### Releasing

1. When changesets land on `main`, `.github/workflows/publish.yml` opens or updates the release PR `chore(release): version packages` on the branch `changeset-release/main` by running `pnpm version-packages` (Changesets bumps and changelogs). Later changesets fold into the same PR.
2. The release PR is opened with the workflow's `GITHUB_TOKEN`, and GitHub does not start workflows for events that token causes, so CI does not run on it by itself. Before merging, a person closes and reopens it (`gh pr close <n> && gh pr reopen <n>`) or pushes an empty commit to its branch. `gh workflow run ci.yml` does not count: a dispatched run is not attached to the PR and does not satisfy required checks.
2. The release PR is opened with the workflow's `GITHUB_TOKEN`. GitHub can require an authorized maintainer to select **Approve workflows to run** for its PR events; see [GitHub's trigger behavior](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow). The release workflow does not force the PR into Draft. If it is Draft, mark it Ready after reviewing the changes; reopening or pushing to a Draft PR does not execute full CI. Confirm that the current PR's `test` job actually ran and passed alongside Review before merging. This CI has no manual dispatch trigger.
3. Merging the release PR runs `publish.yml` again: gates, then `pnpm release` publishes unpublished versions to npm through OIDC trusted publishing with provenance. See [`docs/npm-publish.md`](docs/npm-publish.md).

### Bot Pull Requests
Expand Down
17 changes: 10 additions & 7 deletions docs/npm-publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,13 +80,16 @@ pnpm build

After the pull request lands on `main`, GitHub Actions opens or updates the release pull request `chore(release): version packages` on the branch `changeset-release/main`. It runs `pnpm version-packages`: Changesets bumps published packages and writes changelog entries through `@changesets/changelog-github`. Private workspace packages are not versioned.

The release pull request is opened with the workflow's `GITHUB_TOKEN`. GitHub does not start workflows for events caused by that token, so CI does not run on the release pull request by itself. Before merging, close and reopen it as a person, or push an empty commit to its branch:

```bash
gh pr close <n> && gh pr reopen <n>
```

That is a normal `pull_request` event, so `CI` and `Review` run. `gh workflow run ci.yml` does not help: a dispatched run is not attached to the pull request and does not satisfy required checks.
The release pull request is opened with the workflow's `GITHUB_TOKEN`. GitHub can require an authorized
maintainer to select **Approve workflows to run** for PR events created by that token; see
[GitHub's trigger 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 release workflow does not force Draft. If the PR is Draft, mark it Ready after reviewing the changes;
reopening or pushing to a PR that is still Draft does not execute the full CI job.

Confirm that the full `test` job actually ran and passed for the current head and merge result, alongside the
lightweight Review checks, before merging. A skipped Draft job is not test evidence. The CI workflow has no
manual dispatch trigger. See [CI Execution Policy](../CONTRIBUTING.md#ci-execution-policy) for the shared
Ready/Draft behavior; the existing publishing process is unchanged.

Merging the release pull request runs `pnpm release`, which builds the packages and publishes unpublished package versions through Changesets. Changesets runs `pnpm publish`, which authenticates through npm trusted publishing (OIDC) and attaches provenance itself because the repository and the packages are public.

Expand Down
Loading