@maverickcer/env-cap 0.7.4 → 0.7.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADOPTION.md +106 -124
- package/AGENTS.md +14 -13
- package/CHANGELOG.md +15 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +81 -76
- package/RELEASING.md +17 -15
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +68 -105
- package/benchmarks/READING-BENCHMARKS.md +13 -7
- package/benchmarks/WRITING-BENCHMARKS.md +1 -1
- package/dist/.dts/_ipc/build-fs.d.ts +9 -14
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +6 -6
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +8 -3
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +1 -1
- package/dist/.dts/runtime/create.d.ts +3 -0
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +7 -4
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/types.d.ts +16 -0
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +14 -1
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +22 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +47 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +62 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +170 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +176 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +101 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +95 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +105 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +223 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +47 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +35 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +59 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +207 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +170 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +52 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +23 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +135 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +2 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +223 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +191 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-6XFHJFQK.js → build-DNAYWD2B.js} +8 -5
- package/dist/build-DNAYWD2B.js.map +1 -0
- package/dist/build.cjs +7 -4
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +7 -4
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-RL5KFVUT.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +27 -4
- package/schemas/env-cap-report.schema.json +1 -1
- package/skills/env-cap/SKILL.md +1 -1
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +2 -2
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +14 -2
- package/dist/build-6XFHJFQK.js.map +0 -1
- /package/dist/{chunk-RL5KFVUT.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/CODE_REVIEW.md
CHANGED
|
@@ -1,200 +1,96 @@
|
|
|
1
1
|
# Reviewing changes to env-cap
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
answers one question: **what makes a change to this package safe to merge?**
|
|
5
|
-
It is not a second contributor guide and not a style checklist — CI already
|
|
6
|
-
enforces formatting, lint, types, coverage, and mutation score. This
|
|
7
|
-
document covers the judgement calls CI can't make.
|
|
3
|
+
A change is safe to merge when CI is green, no invariant below has moved, and every surface change is declared. CI checks formatting, lint, types, coverage and mutation; this list covers the rest. [`CONTRIBUTING.md`](CONTRIBUTING.md) is the author's side.
|
|
8
4
|
|
|
9
5
|
## 1. Review standard
|
|
10
6
|
|
|
11
|
-
A change is ready to merge when all of
|
|
7
|
+
A change is ready to merge when all of these hold:
|
|
12
8
|
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- Every invariant in §2 that the change touches
|
|
18
|
-
|
|
19
|
-
- Any
|
|
20
|
-
|
|
21
|
-
- Any generated artifact in the diff (§4) has been reviewed as output, not
|
|
22
|
-
skimmed.
|
|
23
|
-
- The change doesn't weaken a capability boundary (§5).
|
|
9
|
+
- The `contract` and `lint` checks are green; the branch ruleset requires both.
|
|
10
|
+
- Every other CI job is green too. They are the Bun and Deno suite, the examples, the integration fixtures, `typescript-5`, `typescript-compat` and the package-manager smoke test.
|
|
11
|
+
- The `required` check waits for those jobs, but the ruleset does not yet require `required`, so a reviewer must look.
|
|
12
|
+
- `benchmark-pr` is green. A failure there skips `lint`, `verify` and `contract`, which GitHub then counts as passing; check it by hand.
|
|
13
|
+
- Every invariant in §2 that the change touches still holds, checked in the code, not the description.
|
|
14
|
+
- Any public-surface change (§3) is intended, explained, and carries the right changeset.
|
|
15
|
+
- Any generated artifact in the diff (§4) has been read as output.
|
|
16
|
+
- No capability boundary is weakened (§5).
|
|
24
17
|
|
|
25
|
-
When a change
|
|
26
|
-
that keeps an invariant intact beats a complete one that bends it "just for
|
|
27
|
-
now."
|
|
18
|
+
When a change cannot meet this bar in one pull request, split it.
|
|
28
19
|
|
|
29
20
|
## 2. Package invariants
|
|
30
21
|
|
|
31
|
-
These are
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- **
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
- **
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
fires, nothing is written
|
|
54
|
-
([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
55
|
-
- **Capability ownership — no global env object**
|
|
56
|
-
([ADR 0003](specs/decisions/0003-no-global-env-object.md)). Reject any
|
|
57
|
-
merged/global wrapper over multiple contracts.
|
|
58
|
-
- **Contracts self-redact; errors never carry values**
|
|
59
|
-
([ADR 0006](specs/decisions/0006-self-redacting-contracts.md)). Read
|
|
60
|
-
every new/changed error message, log line, and fixture: a raw or
|
|
61
|
-
processed env value must never appear. This is the single highest-value
|
|
62
|
-
thing to check by eye.
|
|
63
|
-
- **`--check` computes before it compares and never partially writes**
|
|
64
|
-
([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
65
|
-
|
|
66
|
-
If a change genuinely needs to move one of these boundaries, it needs its
|
|
67
|
-
own ADR first (see [`CONTRIBUTING.md`](CONTRIBUTING.md#adding-an-architecture-decision-record-adr)),
|
|
68
|
-
not a reviewer waving it through.
|
|
69
|
-
|
|
70
|
-
## 3. Public API / stability review
|
|
71
|
-
|
|
72
|
-
[`VERSIONING.md`](VERSIONING.md) defines three tiers. Before approving:
|
|
73
|
-
|
|
74
|
-
- **Stable** (public runtime APIs, the four documented `generate*()` build
|
|
75
|
-
orchestrators, every `env-cap --help` flag, `--json` output, the
|
|
76
|
-
published JSON Schema, the generated manifest shape, the ESLint plugin's
|
|
77
|
-
rule names/options). A breaking change here needs a `major` changeset and
|
|
78
|
-
an explicit "yes, we're doing this" in the PR. An _additive_ change
|
|
79
|
-
(new optional flag, new optional option field, new export) is `minor` —
|
|
80
|
-
confirm it's genuinely additive and doesn't change a default.
|
|
81
|
-
- **`--json` and the JSON Schema** are versioned by their own
|
|
82
|
-
`schemaVersion` ([ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md),
|
|
83
|
-
[ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md)).
|
|
84
|
-
Additive field: no bump. Changed/removed field: `schemaVersion` bump +
|
|
85
|
-
`major`. The schema is generated from the types (`npm run schema`) —
|
|
86
|
-
confirm the committed `schemas/*.json` in the diff matches.
|
|
87
|
-
- **Experimental** (the `packages` option, the lower-level `./build`
|
|
88
|
-
primitives, `./evidence`, `generateEvidenceModel` and friends). May
|
|
89
|
-
change shape in a `minor`/`patch` — but the change should still be
|
|
90
|
-
deliberate, and the ADR's Status line should reflect reality.
|
|
91
|
-
- **Private** (anything not re-exported, all AST-traversal internals, the
|
|
92
|
-
dependency-ownership engine internals per
|
|
93
|
-
[ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)).
|
|
94
|
-
No bump, but check the change didn't leak an internal into a public
|
|
95
|
-
entry point.
|
|
96
|
-
|
|
97
|
-
Check `package.json#exports` in the diff: the allowed set is exactly `.`,
|
|
98
|
-
`./build`, `./node`, `./helpers`, `./evidence`, `./eslint-plugin`,
|
|
99
|
-
`./schema`, `./schema/*`, `./package.json`. A new entry is a public-surface
|
|
100
|
-
decision.
|
|
22
|
+
These are listed in [`AGENTS.md`](AGENTS.md) ("Non-negotiable invariants") and pinned by ADRs. Check that the change does not erode one, even indirectly:
|
|
23
|
+
|
|
24
|
+
- **Schemas are never executed** ([ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)). Reject any change that adds `import()`, `require()`, `eval`, `new Function`, `vm`, a worker or a subprocess to the analysis path. Lint bans `eval` and `new Function`; the rest is yours to catch. An unresolvable value must surface as a finding, never a guess.
|
|
25
|
+
- **The runtime stays isomorphic and within budget** ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md), [ADR 0008](specs/decisions/0008-gzip-size-budget.md)). `src/runtime` and `src/helpers` must not import `node:*` or add a dependency. The browser-bundle test catches a Node import; nothing catches a third-party import.
|
|
26
|
+
- **Only `src/cli` may import `node:fs`.** ESLint enforces it in `src/`. `src/build` uses `node:path` and `typescript` and takes its filesystem from the caller. No runtime entry may reach `src/build`; `compiler-isolation` checks that.
|
|
27
|
+
- **Warn, do not throw, by default** ([ADR 0005](specs/decisions/0005-warn-not-throw-by-default.md)). New data-quality findings are warnings. Escalation happens only behind a `--strict*` flag or an `on*: "throw"` option, and nothing is written when it fires ([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
28
|
+
- **No global env object** ([ADR 0003](specs/decisions/0003-no-global-env-object.md)). Reject any wrapper that merges contracts.
|
|
29
|
+
- **Errors never carry values** ([ADR 0006](specs/decisions/0006-self-redacting-contracts.md)). Read every new or changed error message, log line and fixture for a raw or processed value. This is the most valuable thing to check by eye.
|
|
30
|
+
- **`--check` computes before it compares and never writes** ([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
31
|
+
|
|
32
|
+
Moving one of these boundaries needs its own ADR first ([CONTRIBUTING.md](CONTRIBUTING.md#adding-an-architecture-decision-record-adr)).
|
|
33
|
+
|
|
34
|
+
## 3. Public API and stability review
|
|
35
|
+
|
|
36
|
+
[`VERSIONING.md`](VERSIONING.md) lists every entry point and its tier. Every entry point is Stable today; nothing ships Experimental ([ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)).
|
|
37
|
+
|
|
38
|
+
- **Stable.** A breaking change needs a `major` changeset from 1.0, or a `minor` before 1.0, and an explicit decision in the pull request. In a hand-written changeset, an additive change is `minor`; confirm it does not change a default. `ApiContract` and `SurfaceContract` fail when the declared level is too low.
|
|
39
|
+
- **`--json` and the JSON Schema.** An additive field needs no `schemaVersion` bump. A changed or removed field needs a `schemaVersion` bump and a breaking changeset ([ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md), [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md)). No check ties the shape change to the bump, so check it here.
|
|
40
|
+
- **The schema is generated** from the types by `npm run schema`. The `Schema` check fails if the committed file differs.
|
|
41
|
+
- **Private.** Anything not re-exported, the AST-traversal internals, and the dependency-ownership engine ([ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)). No bump, but check nothing internal leaked into an entry point.
|
|
42
|
+
|
|
43
|
+
Check `package.json#exports` in the diff. The allowed set is `.`, `./build`, `./node`, `./helpers`, `./evidence`, `./eslint-plugin`, `./schema`, `./schema/*` and `./package.json`. A new entry is a public-surface decision and needs a row in `docs/surface.json`.
|
|
101
44
|
|
|
102
45
|
## 4. Generated-artifact review
|
|
103
46
|
|
|
104
|
-
env-cap
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
-
|
|
109
|
-
|
|
110
|
-
description is not a substitute for looking at what changed in them.
|
|
111
|
-
- Confirm the artifact was regenerated by the tool, not hand-edited — files
|
|
112
|
-
marked `AUTO-GENERATED FILE. DO NOT EDIT.` must only change via their
|
|
113
|
-
generator.
|
|
114
|
-
- If an example's `expected/` tree changed, the source `env.schema.ts` /
|
|
115
|
-
`documentEnv()` change that caused it must be in the same PR and must
|
|
116
|
-
explain the delta.
|
|
117
|
-
- If `schemas/*.json` changed without a corresponding types change, that's
|
|
118
|
-
a red flag — the schema is generated from the types.
|
|
47
|
+
env-cap commits its own generated files: `schemas/*.json`, `docs/api-report/`, the flagship examples' `docs/` and manifests, and the integration fixtures' `expected/` trees. When one appears in a diff:
|
|
48
|
+
|
|
49
|
+
- **Read it as output.** A schema or golden diff is the observable behaviour change. "Regenerated goldens" in a description does not replace reading them.
|
|
50
|
+
- Confirm a generator wrote it. A file marked as generated changes only through its generator.
|
|
51
|
+
- If an example's generated `docs/` changed, the schema or `documentEnv()` change that caused it must be in the same pull request.
|
|
52
|
+
- If `schemas/*.json` changed without a matching type change, that is a red flag.
|
|
119
53
|
|
|
120
54
|
## 5. Security and capability-boundary review
|
|
121
55
|
|
|
122
|
-
- The static-analysis
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
- the `AmbientCapabilities` check enforces that runtime/helpers acquire no ambient
|
|
128
|
-
filesystem capability; `src/build` receives its filesystem explicitly
|
|
129
|
-
from the CLI ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
|
|
130
|
-
A change that reaches for `node:fs` directly inside a library surface
|
|
131
|
-
breaks this — reject it.
|
|
132
|
-
- Dependency scanning stays within the bounds described in
|
|
133
|
-
[`SECURITY.md`](SECURITY.md) — no unbounded traversal of `node_modules`.
|
|
134
|
-
- Validation `context` is a participation filter, **not** a security or
|
|
135
|
-
bundling boundary ([ADR 0022](specs/decisions/0022-validation-contexts.md),
|
|
136
|
-
[ADR 0004](specs/decisions/0004-no-client-server-package-split.md)). Reject
|
|
137
|
-
any change or doc that implies otherwise.
|
|
138
|
-
- New dependency (runtime _or_ dev): scrutinize. The runtime tier allows
|
|
139
|
-
zero; a dev dependency needs a real justification in the PR.
|
|
56
|
+
- The static-analysis rule (§2) is a security boundary. env-cap runs on untrusted repository content: schema files, `tsconfig.json`, package metadata. Anything that could run that content, or read outside the declared roots, is a vulnerability.
|
|
57
|
+
- The `AmbientCapabilities` check allows `fs` only in the CLI, `./node` and the ESLint plugin. A library surface that reaches for `node:fs` breaks this; reject it.
|
|
58
|
+
- Dependency scanning stays within the bounds in [`SECURITY.md`](SECURITY.md#build-time-security-model).
|
|
59
|
+
- A validation `context` is a participation filter, not a security or bundling boundary ([ADR 0022](specs/decisions/0022-validation-contexts.md), [ADR 0004](specs/decisions/0004-no-client-server-package-split.md)). Reject a change or a document that implies otherwise.
|
|
60
|
+
- A new dependency, runtime or dev, needs scrutiny. The runtime entries allow none; a dev dependency needs a reason in the pull request.
|
|
140
61
|
|
|
141
62
|
## 6. AI-authored change review
|
|
142
63
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
- **
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
`--flag` that looks reasonable but expands the Stable surface without a
|
|
154
|
-
decision. Cross-check `package.json#exports` and the `--help` text in the
|
|
155
|
-
diff against [`VERSIONING.md`](VERSIONING.md) §Stable and
|
|
156
|
-
[`AGENTS.md`](AGENTS.md) invariant 4.
|
|
157
|
-
- **Documentation fields in the wrong call.** `description`/`owner`/
|
|
158
|
-
`expiresAt` placed inside `createEnv()` instead of `documentEnv()` —
|
|
159
|
-
[`AGENTS.md`](AGENTS.md) invariant 3.
|
|
160
|
-
- **Framework accretion.** A manager/registry/provider wrapper around
|
|
161
|
-
`validateEnv()` — [`AGENTS.md`](AGENTS.md) "Avoid".
|
|
162
|
-
- **Tests that assert the bug.** A regenerated golden or a new test that
|
|
163
|
-
simply encodes whatever the code now does. Confirm the _expected_ value
|
|
164
|
-
is correct independently, not just internally consistent.
|
|
165
|
-
- **Mutation-score gaming.** A test added only to kill a mutant, asserting
|
|
166
|
-
nothing meaningful. The mutation gate is a floor, not the goal — a test
|
|
167
|
-
must assert real behavior.
|
|
168
|
-
|
|
169
|
-
[`AGENTS.md`](AGENTS.md), [`PROMPT.md`](PROMPT.md), and
|
|
170
|
-
[`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) are the invariant set
|
|
171
|
-
an assistant was (or should have been) working against — a reviewer can use
|
|
172
|
-
the same list.
|
|
64
|
+
A pull request written with an AI assistant gets the same scrutiny. Its common failure modes are specific:
|
|
65
|
+
|
|
66
|
+
- **Silent invariant drift:** a fallback that executes a schema, a value embedded in an error to be "helpful", or `node:fs` in a helper. Check every new `catch`, fallback and error string against §2.
|
|
67
|
+
- **Plausible API additions:** a new export or flag that widens the Stable surface without a decision. Compare `package.json#exports` and `--help` in the diff with [`VERSIONING.md`](VERSIONING.md).
|
|
68
|
+
- **Documentation fields in the wrong call:** `description`, `owner` or `expiresAt` inside `createEnv()` instead of `documentEnv()`.
|
|
69
|
+
- **Framework accretion:** a manager, registry or provider around `validateEnv()`.
|
|
70
|
+
- **Tests that assert the bug:** a regenerated golden or a test that encodes whatever the code now does. Confirm the expected value independently.
|
|
71
|
+
- **Mutation gaming:** a test that kills a mutant but asserts nothing meaningful.
|
|
72
|
+
|
|
73
|
+
[`AGENTS.md`](AGENTS.md), [`PROMPT.md`](PROMPT.md) and [`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) are the rules an assistant works against; use the same list.
|
|
173
74
|
|
|
174
75
|
## 7. Required verification
|
|
175
76
|
|
|
176
|
-
- `npm run verify` green locally or in CI.
|
|
177
|
-
-
|
|
178
|
-
|
|
179
|
-
-
|
|
180
|
-
|
|
181
|
-
- `npm run
|
|
182
|
-
- The example `expected/` goldens regenerated (`npm run examples:update-golden`)
|
|
183
|
-
and reviewed if generated output changed.
|
|
184
|
-
- The committed Markdown API report regenerated (`npm run docs:api:report`)
|
|
185
|
-
and committed if any public export changed — CI's `docs:api:report:check`
|
|
186
|
-
fails otherwise. The report diff _is_ the API-surface diff; read it.
|
|
77
|
+
- `npm run verify` green, locally or in CI.
|
|
78
|
+
- Coverage floors in `vitest.config.ts` not lowered without a stated reason.
|
|
79
|
+
- Mutation: the `contract` job fails on any surviving, timed-out or uncovered mutant. New logic needs tests that assert behaviour.
|
|
80
|
+
- `npm run size` if `src/runtime`, `src/helpers` or `src/evidence` changed.
|
|
81
|
+
- Integration-fixture goldens regenerated with `npm run examples:update-golden`, and read, if generated output changed.
|
|
82
|
+
- The API report regenerated with `npm run docs:api:report` if a public export or its TSDoc changed. The `ApiDocsReport` check fails otherwise. The report diff is the API diff; read it.
|
|
187
83
|
|
|
188
84
|
## 8. Approval checklist
|
|
189
85
|
|
|
190
|
-
- [ ]
|
|
191
|
-
- [ ] Every touched invariant in §2 re-checked against the
|
|
192
|
-
- [ ] No raw
|
|
193
|
-
- [ ] Public-surface changes
|
|
194
|
-
- [ ] `package.json#exports` unchanged, or the new entry is a
|
|
195
|
-
- [ ] `--json`
|
|
196
|
-
- [ ] Generated artifacts in the diff
|
|
197
|
-
- [ ] `docs/api-report/` regenerated
|
|
86
|
+
- [ ] `contract` and `lint` green, and every other CI job green
|
|
87
|
+
- [ ] Every touched invariant in §2 re-checked against the code
|
|
88
|
+
- [ ] No raw or processed value in any error, log or fixture
|
|
89
|
+
- [ ] Public-surface changes intended, with the right changeset
|
|
90
|
+
- [ ] `package.json#exports` unchanged, or the new entry is a decision
|
|
91
|
+
- [ ] `--json` and JSON Schema changes carry the right `schemaVersion` treatment
|
|
92
|
+
- [ ] Generated artifacts in the diff read as output
|
|
93
|
+
- [ ] `docs/api-report/` regenerated if a public export changed
|
|
198
94
|
- [ ] No new runtime dependency; any new dev dependency justified
|
|
199
|
-
- [ ] Coverage not lowered;
|
|
95
|
+
- [ ] Coverage floors not lowered without a reason; no surviving mutants
|
|
200
96
|
- [ ] An ADR added if a structural boundary moved
|
package/CONTRIBUTING.md
CHANGED
|
@@ -1,32 +1,52 @@
|
|
|
1
1
|
# Contributing to env-cap
|
|
2
2
|
|
|
3
|
+
A change needs a branch, tests, a changeset and green `contract` and `lint` checks. The steps below go from clone to merge; [CODE_REVIEW.md](CODE_REVIEW.md) covers the reviewer's side.
|
|
4
|
+
|
|
3
5
|
## Development setup
|
|
4
6
|
|
|
5
7
|
```bash
|
|
6
8
|
git clone https://github.com/maverickcer/env-cap.git
|
|
7
9
|
cd env-cap
|
|
8
|
-
npm install
|
|
10
|
+
npm run setup # install, build, regenerate the schema, and install the git hooks
|
|
9
11
|
```
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
`npm run setup` installs the optional shared git hooks (`internal-package-contract install-hooks`):
|
|
14
|
+
|
|
15
|
+
| Hook | What it runs |
|
|
16
|
+
| ---------- | --------------------------------------------------------- |
|
|
17
|
+
| pre-commit | The contract checks the staged change can reach |
|
|
18
|
+
| pre-push | Most of the contract, without Coverage, Crap and Mutation |
|
|
19
|
+
| commit-msg | The Conventional Commits format check |
|
|
20
|
+
|
|
21
|
+
The hooks are a convenience and can be bypassed. CI is the gate.
|
|
22
|
+
|
|
23
|
+
## Local checks
|
|
24
|
+
|
|
25
|
+
`npm run verify` runs what CI's `verify` and `lint` jobs run, plus the schema and README-example checks:
|
|
12
26
|
|
|
13
27
|
```bash
|
|
14
|
-
npm run verify # typecheck
|
|
28
|
+
npm run verify # typecheck, lint, format, build, schema, coverage, size, ambient, isolation, API-report and README-example checks
|
|
15
29
|
```
|
|
16
30
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
31
|
+
The `contract` job runs `npm run contract` on top of it. Run single steps when you need them:
|
|
32
|
+
|
|
33
|
+
| Command | What it does |
|
|
34
|
+
| ------------------------- | -------------------------------------------------------------- |
|
|
35
|
+
| `npm run typecheck` | Type-check the repository |
|
|
36
|
+
| `npm run build` | Build `dist/` |
|
|
37
|
+
| `npm test` | Run the tests once; `npm run test:watch` keeps them running |
|
|
38
|
+
| `npm run test:coverage` | Run the tests with the coverage floors from `vitest.config.ts` |
|
|
39
|
+
| `npm run lint` | Run ESLint |
|
|
40
|
+
| `npm run size` | Check the gzip budgets in `ci/size-budgets.mjs` |
|
|
41
|
+
| `npm run docs:api` | Generate the TypeDoc site into `docs/api/` |
|
|
42
|
+
| `npm run docs:api:report` | Regenerate the Markdown API report in `docs/api-report/` |
|
|
43
|
+
| `npm run contract` | Run the whole contract; add `-- --checks A,B` for named checks |
|
|
21
44
|
|
|
22
45
|
### Working with `examples/`
|
|
23
46
|
|
|
24
|
-
Each example under [`examples/`](examples/) is its own npm project
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
change intentionally alters generated output (manifest/docs/`.env.example`/ownership-report
|
|
28
|
-
formatting, ordering, or serialization), regenerate every example's goldens and review the
|
|
29
|
-
diff before committing:
|
|
47
|
+
Each example under [`examples/`](examples/) is its own npm project; run `npm install` inside it. None of the examples keeps an `expected/` tree of env-cap output. `enterprise-platform/expected/output.json` is that example's own smoke-test fixture. Their committed `docs/`, `.env.example` and `src/generated/env.manifest.ts` are the golden output, and each example's `check` script compares them with a fresh run ([examples/README.md](examples/README.md#golden-regression-testing)).
|
|
48
|
+
|
|
49
|
+
The integration fixtures under `test/integration/` keep `expected/` directories. When your change alters generated output on purpose, regenerate everything and read the diff:
|
|
30
50
|
|
|
31
51
|
```bash
|
|
32
52
|
npm run examples:update-golden
|
|
@@ -35,97 +55,60 @@ npm run examples:update-golden
|
|
|
35
55
|
## Making a change
|
|
36
56
|
|
|
37
57
|
1. Branch from `main`.
|
|
38
|
-
2. Make your change. If it touches a
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
4. Run `npx changeset` and describe your change from the consumer's
|
|
47
|
-
perspective (not "what I changed in the code", but "what changes for
|
|
48
|
-
someone who installs this package"). Pick `patch`/`minor`/`major`
|
|
49
|
-
according to [`VERSIONING.md`](VERSIONING.md)'s stable/experimental/private
|
|
50
|
-
split — a change to something documented as Experimental is never
|
|
51
|
-
`major`, even if it's breaking, since Experimental surfaces are explicitly
|
|
52
|
-
exempted from the stability guarantee until they're promoted to stable.
|
|
53
|
-
5. Open a pull request. CI runs `npm run verify`, `npm run lint`, coverage
|
|
54
|
-
thresholds, and the Bun/Deno cross-runtime conformance suite.
|
|
58
|
+
2. Make your change. If it touches a surface in [`VERSIONING.md`](VERSIONING.md)'s Stable tier, decide whether it is breaking, additive or a fix.
|
|
59
|
+
3. Add or update tests. `npm run test:coverage` fails below the floors in `vitest.config.ts`. Floors are raised in review when coverage improves. Lowering one is a reviewed change, never a silent one.
|
|
60
|
+
4. Run `npx changeset` and describe what changes for someone who installs the package. Pick `patch`, `minor` or `major` by [`VERSIONING.md`](VERSIONING.md). If you add none, the release workflow generates one from `feat`, `fix`, `perf` and `revert` commit messages; other types release nothing.
|
|
61
|
+
5. Open a pull request. A merge needs the `contract` and `lint` checks; `contract` fails when `verify` or `lint` fails.
|
|
62
|
+
|
|
63
|
+
CI also runs the Bun and Deno suite, the examples, the integration fixtures, `typescript-5`, `typescript-compat` and the package-manager smoke test. The `required` check waits for all of them. The branch ruleset does not yet require `required`, so those jobs do not yet block a merge. Treat a red one as blocking anyway.
|
|
64
|
+
|
|
65
|
+
`benchmark-pr` needs the same care. A failure there skips `lint`, `verify` and `contract`, which GitHub then counts as passing; check it by hand.
|
|
55
66
|
|
|
56
67
|
## Adding an Architecture Decision Record (ADR)
|
|
57
68
|
|
|
58
|
-
`specs/decisions/` records
|
|
59
|
-
just what it does today — `specs/architecture.md` is the current-state
|
|
60
|
-
summary; ADRs are the reasoning trail. Add one when a change:
|
|
69
|
+
`specs/decisions/` records why the project is shaped the way it is. `specs/architecture.md` summarizes the current state. Add an ADR when a change:
|
|
61
70
|
|
|
62
|
-
- introduces a
|
|
63
|
-
|
|
64
|
-
-
|
|
65
|
-
reintroduce without knowing it was already considered and rejected, or
|
|
66
|
-
- changes the boundary of what the runtime/build/helpers packages are
|
|
67
|
-
responsible for.
|
|
71
|
+
- introduces a constraint or guarantee an application could rely on, such as "warn, not throw, by default";
|
|
72
|
+
- closes off an approach a future contributor might reintroduce without knowing it was rejected; or
|
|
73
|
+
- moves the boundary of what the runtime, build or helpers entry points are responsible for.
|
|
68
74
|
|
|
69
|
-
A one-line
|
|
70
|
-
does not need one.
|
|
75
|
+
A one-line fix or an internal refactor with no observable change needs no ADR.
|
|
71
76
|
|
|
72
|
-
**Numbering
|
|
73
|
-
current highest number — gaps are possible if a numbered decision was
|
|
74
|
-
retroactively backfilled out of order; don't reuse a number even if a file
|
|
75
|
-
for it doesn't exist yet).
|
|
77
|
+
**Numbering:** run `npx internal-package-contract new` for the next unused number and the sections. Never reuse a number, even if its file is missing.
|
|
76
78
|
|
|
77
|
-
**Structure**,
|
|
78
|
-
or `0009-exclusive-groups-are-always-errors.md` for full examples):
|
|
79
|
+
**Structure**, from the existing ADRs (see `0002-static-analysis-never-execution.md` or `0009-exclusive-groups-are-always-errors.md`):
|
|
79
80
|
|
|
80
81
|
```markdown
|
|
81
|
-
# NNNN: <short
|
|
82
|
+
# NNNN: <short title that states the decision>
|
|
82
83
|
|
|
83
84
|
## Status
|
|
84
85
|
|
|
85
86
|
Accepted. Implemented in `path/to/file.ts`.
|
|
86
|
-
<!-- or: Proposed / Experimental, if the decision ships behind an explicit
|
|
87
|
-
Experimental label per VERSIONING.md -->
|
|
88
87
|
|
|
89
88
|
## Context
|
|
90
89
|
|
|
91
|
-
What problem existed, what constraints applied, and what would happen
|
|
92
|
-
|
|
93
|
-
problem.
|
|
90
|
+
What problem existed, what constraints applied, and what would happen without this decision.
|
|
91
|
+
Name specific files and functions.
|
|
94
92
|
|
|
95
93
|
## Decision
|
|
96
94
|
|
|
97
|
-
What was
|
|
98
|
-
could verify the codebase still matches it.
|
|
95
|
+
What was decided, concretely enough that a reader could check the code still matches it.
|
|
99
96
|
|
|
100
97
|
## Consequences
|
|
101
98
|
|
|
102
|
-
What this makes possible, what it
|
|
103
|
-
future contributor should know about before "fixing" what looks like a
|
|
104
|
-
limitation.
|
|
99
|
+
What this makes possible, what it rules out, and any trade-off a future contributor should know.
|
|
105
100
|
|
|
106
101
|
## Alternatives considered
|
|
107
102
|
|
|
108
|
-
Each rejected alternative, and the
|
|
109
|
-
"more complex," but what concrete problem the complexity would or wouldn't
|
|
110
|
-
have solved.
|
|
103
|
+
Each rejected alternative, and the concrete reason it was rejected.
|
|
111
104
|
```
|
|
112
105
|
|
|
113
|
-
|
|
114
|
-
it documents a structural boundary, not just a narrower implementation
|
|
115
|
-
choice.
|
|
106
|
+
Add the new ADR to `specs/architecture.md`'s decision table if it records a structural boundary.
|
|
116
107
|
|
|
117
108
|
## Release process (maintainers)
|
|
118
109
|
|
|
119
|
-
Releases
|
|
120
|
-
whole process — the normal flow, first-time trusted-publisher setup, and
|
|
121
|
-
how to recover a failed or wrong publish — lives in
|
|
122
|
-
[`RELEASING.md`](RELEASING.md). Contributors don't run any of it; a change
|
|
123
|
-
ships by merging a PR that carries a changeset.
|
|
110
|
+
Releases use Changesets and npm OIDC trusted publishing. They are automated after a person merges the release pull request. [`RELEASING.md`](RELEASING.md) covers the normal flow, first-time setup and recovery. Contributors run none of it. A change ships when its pull request merges and the next release pull request merges after it.
|
|
124
111
|
|
|
125
112
|
## Versioning and stability
|
|
126
113
|
|
|
127
|
-
|
|
128
|
-
versioning, what's Experimental, and what's a private implementation detail
|
|
129
|
-
that can change without notice. When in doubt about whether your change is
|
|
130
|
-
breaking, ask in the pull request rather than guessing at the changeset bump
|
|
131
|
-
type — an incorrect bump type is harder to fix after release than before.
|
|
114
|
+
[`VERSIONING.md`](VERSIONING.md) lists what semver covers, tier by tier. If you are unsure whether a change is breaking, ask in the pull request. A wrong bump type is harder to fix after a release than before.
|