You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 07f082e
Browse filesBrowse the repository at this point in the historyBrowse files
docs(release): assert latest on the bootstrap with the registry's own definition, and pin every preparation trigger
A packument's dist-tags are an object with at least one key, latest (npm/registry REGISTRY-API.md), so a first publish carries latest whatever --tag asked for; the docs, the setup step, and the stable verdict's comment say so with that citation, replacing the two-outcome hedge. The bootstrap step gains the dist-tag check and drops the prepare script from the manifest as both CI publishers do.
PREPARATION_SCRIPTS is exported and the test fixture carries one of each trigger, so dropping any of the six from the list fails the suite; the planter predicate is named for what it decides. AGENTS.md's bundle sentence places the release's packaged commit on the build chain (a child of the previous tip or a root), never as a child of the release commit.
<!-- Add project-specific instructions below the END marker; they are this repository's own and survive every sync. -->
35
35
<!-- END REPO-PLATFORM MANAGED -->
36
36
37
-
- `lib/settings.schema.json` is the COMMITTED JSON Schema for settings.yml, generated from the zod slices in `src/sections/<key>/schema.ts` as composed into the settings document by `src/schema.ts`. Each slice is ONE declaration that produces its config type (z.infer), the section's tolerant runtime shape (the section module derives `loosen(<slice>)` itself; the factory-minted families - secrets, variables, the two setup sections, and the list sections on `listSection` - get it from their shared factory in `src/sections/shared/`, which does that derivation once), and its part of the published schema (`.meta({id})` names its definitions; the descriptions come from the `schema:` map in the section's `<key>.docs.yml`, keyed `Definition.field`, which the generator attaches and fails on when a site or a key is unmatched); `src/schema.ts` adds only the document-level wrappers and pins each property to its slice with a lockstep type. Regenerate the schema with `bun run build:schema` after a schema-affecting `src/` change - CI's schema-check job fails when it drifts. `lib/index.js`, the bundled entrypoint the action runs (node24), is NOT committed on main: every workflow that executes the action builds it first (`bun run build:bundle`), the e2e runner builds it to a temp path, and a release builds and commits it on a packaged child of the release commit, which is what every `vX.Y.Z` tag and the moving major point at (main itself stays source-only). `lib/` is exempt from the typography check (third-party unicode in the bundle; the schema descriptions are checked at source) and excluded from [biome](https://biomejs.dev).
37
+
- `lib/settings.schema.json` is the COMMITTED JSON Schema for settings.yml, generated from the zod slices in `src/sections/<key>/schema.ts` as composed into the settings document by `src/schema.ts`. Each slice is ONE declaration that produces its config type (z.infer), the section's tolerant runtime shape (the section module derives `loosen(<slice>)` itself; the factory-minted families - secrets, variables, the two setup sections, and the list sections on `listSection` - get it from their shared factory in `src/sections/shared/`, which does that derivation once), and its part of the published schema (`.meta({id})` names its definitions; the descriptions come from the `schema:` map in the section's `<key>.docs.yml`, keyed `Definition.field`, which the generator attaches and fails on when a site or a key is unmatched); `src/schema.ts` adds only the document-level wrappers and pins each property to its slice with a lockstep type. Regenerate the schema with `bun run build:schema` after a schema-affecting `src/` change - CI's schema-check job fails when it drifts. `lib/index.js`, the bundled entrypoint the action runs (node24), is NOT committed on main: every workflow that executes the action builds it first (`bun run build:bundle`), the e2e runner builds it to a temp path, and a release builds and commits it on the `build` branch's chain commit for the release commit (a child of the previous chain tip, or a root; never a child of the release commit), which is what every `vX.Y.Z` tag and the moving major point at (main itself stays source-only). `lib/` is exempt from the typography check (third-party unicode in the bundle; the schema descriptions are checked at source) and excluded from [biome](https://biomejs.dev).
38
38
- The npm library (`@vivswan/github-settings-as-code`, built into `lib/pkg/` by `bun run build:lib`, never committed) is described in docs/reference/library.md. One rule the tooling cannot infer: a type a section module exposes must be exported from its home module, or the bundled declarations cannot reach it and the package-smoke job fails.
39
39
-`src/cli/` is the command line, a consumer of the public entry like the action: a capability it needs is exported from `src/index.ts` first, never imported across. Guide: docs/start/cli.md.
40
40
- The import layering of `src/` is declared in `architecture.yml` and enforced by `bun run lint:arch`, so a new cross-layer import is a deliberate edit to that file; the module map in `docs/reference/architecture.md` is generated from it.
Copy file name to clipboardExpand all lines: README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,7 +61,7 @@ The [getting started guide](docs/start/getting-started.md) walks the same steps
61
61
62
62
## Library
63
63
64
-
The same engine is the npm package `@vivswan/github-settings-as-code` (ESM, Node 22.14 or newer): validate, merge, check, and apply from your own code. Every green push to `main` publishes a pre-release: `npm install @vivswan/github-settings-as-code@next` (or `bun add`), the install line that always resolves. The plain `npm install @vivswan/github-settings-as-code` gives the released version once one exists; before that it resolves to the bootstrap pre-release or to nothing, depending on what the bootstrap left on `latest`. The [library reference](docs/reference/library.md) has the API by group and the versioning rules.
64
+
The same engine is the npm package `@vivswan/github-settings-as-code` (ESM, Node 22.14 or newer): validate, merge, check, and apply from your own code. Every green push to `main` publishes a pre-release: `npm install @vivswan/github-settings-as-code@next` (or `bun add`). The plain `npm install @vivswan/github-settings-as-code` gives the released version once one exists, and the bootstrap pre-release until then (a first publish carries `latest` whatever tag it asked for). The [library reference](docs/reference/library.md) has the API by group and the versioning rules.
65
65
66
66
The package is also a command: `npx @vivswan/github-settings-as-code@next check --repository o/r --settings-file .github/settings.yml`runs the action's check from a terminal; the [command line guide](docs/start/cli.md) has every command.
Copy file name to clipboardExpand all lines: docs/reference/library.md
+9-16Lines changed: 9 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -168,7 +168,7 @@ The package and the action share one version, the one in `.release-please-manife
168
168
| npm dist-tag | Publishes on | Version | Install |
169
169
|---|---|---|---|
170
170
|`next`| Every green push to `main`| The manifest's next patch, then `-main.<run number>.g<sha7>`: `2.0.1-main.412.gb8df084`|`npm install @vivswan/github-settings-as-code@next`|
171
-
|`latest`| Every release cut | The released version: `2.1.0`. Before the first release, whatever the bootstrap left on `latest`: the pre-release, or nothing (see the setup section)|`npm install @vivswan/github-settings-as-code`|
171
+
|`latest`| Every release cut | The released version: `2.1.0`. Until the first release it names the bootstrap pre-release: a packument always carries `latest` (npm/registry REGISTRY-API.md, "dist-tags: an object with at least one key, latest"), so a first publish gets it whatever `--tag` asked for|`npm install @vivswan/github-settings-as-code`|
172
172
| none | Every packaged commit on the `build` branch since the library joined it | The commit itself |`npm install github:Vivswan/github-settings-as-code#<packaged sha>`|
173
173
174
174
The npm dist-tag `latest` is not the git tag `latest`: the git tag names the newest packaged commit on the `build` branch (every green push moves it), the dist-tag names the newest release on the registry.
@@ -183,25 +183,18 @@ The npm dist-tag `latest` is not the git tag `latest`: the git tag names the new
183
183
184
184
For the owner, once. npm adds a trusted publisher only to a package that already exists, so the first version is published by hand from a maintainer machine with two-factor authentication; it is the only publish a person ever makes.
185
185
186
-
1. From a clean checkout of `main`, build the library (the tarball ships `lib/pkg/`, which is built, not committed), stamp the bootstrap pre-release version, and publish it under `next`, never `latest` by request:
186
+
1. From a clean checkout of `main`, build the library (the tarball ships `lib/pkg/`, which is built, not committed), stamp the bootstrap pre-release version, drop the `prepare` script from the manifest as both CI publishers do, and publish under the `next` dist-tag:
187
187
188
188
```bash
189
189
bun install --frozen-lockfile && bun run build:lib
190
190
version="$(GITHUB_SHA="$(git rev-parse HEAD)" GITHUB_RUN_NUMBER=0 bun .github/scripts/release-pipeline.ts prerelease-version)"
191
-
npm version "$version" --no-git-tag-version && npm publish --access public --tag next
192
-
git checkout package.json
191
+
npm version "$version" --no-git-tag-version && npm pkg delete scripts.prepare
192
+
npm publish --access public --tag next
193
+
git checkout -- package.json
193
194
```
194
195
195
-
Then `npm dist-tag ls @vivswan/github-settings-as-code` shows one of two states; npm's documentation says publishing sets `latest` unless `--tag` is used and is silent on a package's first publish, so neither is promised:
196
+
2. Check the dist-tags: `npm dist-tag ls @vivswan/github-settings-as-code` names the bootstrap version under both `next` and `latest`. The registry gives a package's first publish `latest` whatever `--tag` asked for, because a packument always carries that key (npm/registry REGISTRY-API.md, "dist-tags: an object with at least one key, latest"); the first release takes it over, since the stable publish job yields only to a newer release.
197
+
3. On npmjs.com, on the package's settings page, add a trusted publisher: GitHub Actions, owner `Vivswan`, repository `github-settings-as-code`, workflow filename `ci.yml` (the caller of both hooks), no environment.
198
+
4. Under publishing access, choose "Require two-factor authentication and disallow tokens", so the workflow's OIDC identity is the only thing that can publish.
196
199
197
-
| Dist-tags after the bootstrap | Plain `npm install @vivswan/github-settings-as-code` until the first release |
198
-
|---|---|
199
-
|`next` and `latest`, both on the pre-release | Resolves to the bootstrap pre-release |
200
-
|`next` alone | Fails; `@next` is the install line |
201
-
202
-
The stable publish job handles both: it yields only to a newer release, so the first release takes `latest` from the pre-release or creates it.
203
-
204
-
2. On npmjs.com, on the package's settings page, add a trusted publisher: GitHub Actions, owner `Vivswan`, repository `github-settings-as-code`, workflow filename `ci.yml` (the caller of both hooks), no environment.
205
-
3. Under publishing access, choose "Require two-factor authentication and disallow tokens", so the workflow's OIDC identity is the only thing that can publish.
206
-
207
-
Until step 2 is done, the release hook's `publish-npm` job fails and the GitHub release stays a draft, and `publish-next` fails the same way on the next green push; re-run the failed jobs once the publisher exists.
200
+
Until step 3 is done, the release hook's `publish-npm` job fails and the GitHub release stays a draft, and `publish-next` fails the same way on the next green push; re-run the failed jobs once the publisher exists.
0 commit comments