@rvdbreemen/adr-kit-opencode 0.55.1 → 0.57.0
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/.claude-plugin/plugin.json +1 -1
- package/README.md +11 -11
- package/bin/adr +96 -9
- package/bin/adr-lint +40 -2
- package/bin/adr-migrate +28 -0
- package/bin/adr_catalog.py +12 -34
- package/bin/adr_format.py +185 -4
- package/bin/adr_guardian_queue.py +15 -1
- package/bin/adr_quality_core.py +19 -2
- package/bin/adr_readiness.py +59 -1
- package/bin/adr_schema.py +28 -10
- package/package.json +1 -1
- package/scripts/bump-version.py +8 -1
- package/scripts/check-changelog-sections.py +198 -0
- package/scripts/check-release-version.py +29 -4
- package/scripts/release.py +171 -0
- package/scripts/release_npm.py +117 -0
- package/scripts/release_phases.py +331 -0
- package/scripts/release_shell.py +124 -0
- package/templates/adr-kit-guide.md +7 -2
- package/templates/cc-settings/guardian-hook-entry.json +1 -1
- package/templates/githooks/pre-commit +1 -1
- package/templates/github-workflows/adr-readiness.yml +1 -1
|
@@ -47,6 +47,7 @@ def rank_proposed(report: dict) -> list[dict]:
|
|
|
47
47
|
linked = bool(isinstance(link, dict) and link.get("linked"))
|
|
48
48
|
shipped = bool(item.get("documents_shipped"))
|
|
49
49
|
ready = item.get("classification") == "ready-for-confirmation"
|
|
50
|
+
needs_human = item.get("classification") == "needs-human-input"
|
|
50
51
|
open_questions = bool(item.get("open_questions"))
|
|
51
52
|
age_days = _age_days(item, evaluated_on)
|
|
52
53
|
quality = item.get("quality", {})
|
|
@@ -67,7 +68,14 @@ def rank_proposed(report: dict) -> list[dict]:
|
|
|
67
68
|
# Proposed ADR that is sharp, unlinked, unshipped, not ready and asking
|
|
68
69
|
# nothing has no work attached to it, and listing it teaches the reader
|
|
69
70
|
# to skim the queue.
|
|
70
|
-
|
|
71
|
+
# `needs_human` is here because the classification it names is the one
|
|
72
|
+
# that used to be `ready-for-confirmation`. A record whose References
|
|
73
|
+
# hold only a migration placeholder is unlinked, unshipped, above the
|
|
74
|
+
# quality threshold and asks no open question, so `ready` was its only
|
|
75
|
+
# signal; reporting the placeholder honestly would otherwise drop it out
|
|
76
|
+
# of the queue and make it LESS visible than saying nothing. Measured on
|
|
77
|
+
# ADR-042 with a placeholder: 0 candidates without this line.
|
|
78
|
+
signals = (linked, shipped, ready, open_questions, below_threshold, needs_human)
|
|
71
79
|
if not any(signals):
|
|
72
80
|
continue
|
|
73
81
|
|
|
@@ -80,6 +88,11 @@ def rank_proposed(report: dict) -> list[dict]:
|
|
|
80
88
|
reasons.append("ready for confirmation")
|
|
81
89
|
if open_questions:
|
|
82
90
|
reasons.append("open human questions")
|
|
91
|
+
if needs_human and not open_questions:
|
|
92
|
+
# Before the unconditional age entry on purpose: the SessionStart
|
|
93
|
+
# block prints reasons[:2] and the auto-grill handoff reasons[:3],
|
|
94
|
+
# so a reason appended after it never reaches a human.
|
|
95
|
+
reasons.append("human input needed")
|
|
83
96
|
if below_threshold:
|
|
84
97
|
reasons.append(f"quality {quality_score:.3f} below {threshold:.2f}")
|
|
85
98
|
reasons.append(f"age {age_days} days")
|
|
@@ -98,6 +111,7 @@ def rank_proposed(report: dict) -> list[dict]:
|
|
|
98
111
|
-int(shipped),
|
|
99
112
|
-int(ready),
|
|
100
113
|
-int(open_questions),
|
|
114
|
+
-int(needs_human),
|
|
101
115
|
-int(below_threshold),
|
|
102
116
|
-age_days,
|
|
103
117
|
quality_score,
|
package/bin/adr_quality_core.py
CHANGED
|
@@ -190,6 +190,15 @@ def _section_text(content: str, heading: str) -> str:
|
|
|
190
190
|
return m.group(1) if m else ""
|
|
191
191
|
|
|
192
192
|
|
|
193
|
+
# Same rule as bin/adr-lint: a heading with nothing under it is a hole, not a
|
|
194
|
+
# section. Emptiness only. A migration placeholder counts as content here by
|
|
195
|
+
# decision, not by oversight: an imported record must not fail a blocking gate
|
|
196
|
+
# on arrival (test_adr_policy.py, test_migration_discovery.py). adr-migrate
|
|
197
|
+
# reports the placeholders it wrote instead, which informs without refusing.
|
|
198
|
+
def _is_unfilled(body: str) -> bool:
|
|
199
|
+
return not any(ln.strip() for ln in body.splitlines())
|
|
200
|
+
|
|
201
|
+
|
|
193
202
|
def gate_completeness(content: str) -> Dict:
|
|
194
203
|
"""Gate 1: Completeness (0.0-1.0).
|
|
195
204
|
|
|
@@ -216,9 +225,17 @@ def gate_completeness(content: str) -> Dict:
|
|
|
216
225
|
pattern = _SECTION_PRESENCE_RE.get(section) or re.compile(
|
|
217
226
|
r"^" + re.escape(section) + r"\b", re.MULTILINE
|
|
218
227
|
)
|
|
228
|
+
# A heading with nothing under it is not a section (TASK-198). This loop
|
|
229
|
+
# used to test presence alone, while three checks further down already
|
|
230
|
+
# measured emptiness for Decision, Alternatives and Consequences. That
|
|
231
|
+
# split meant References or Related Decisions could be hollow and still
|
|
232
|
+
# score full marks here, and `adr accept --quality-threshold` reads this
|
|
233
|
+
# score. The placeholder case counts too: it is what adr-migrate writes
|
|
234
|
+
# into a heading it has to add.
|
|
219
235
|
present = bool(pattern.search(content))
|
|
220
|
-
|
|
221
|
-
|
|
236
|
+
filled = present and not _is_unfilled(_section_text(content, section))
|
|
237
|
+
checks[f"section_{section.replace('## ', '').replace(' ', '_').lower()}"] = filled
|
|
238
|
+
if not filled:
|
|
222
239
|
missing_sections.append(section)
|
|
223
240
|
|
|
224
241
|
score = 1.0
|
package/bin/adr_readiness.py
CHANGED
|
@@ -9,7 +9,7 @@ from pathlib import Path
|
|
|
9
9
|
from typing import Dict, List, Optional, Sequence
|
|
10
10
|
|
|
11
11
|
from adr_catalog import build_relationships, load_adr_records, normalize_adr_id
|
|
12
|
-
from adr_format import all_open_questions
|
|
12
|
+
from adr_format import AdrFormatError, all_open_questions, placeholder_required_sections
|
|
13
13
|
from adr_quality_core import QUALITY_THRESHOLD, score_path
|
|
14
14
|
|
|
15
15
|
|
|
@@ -85,6 +85,7 @@ FINDING_CODES = (
|
|
|
85
85
|
"FORMAT_UNKNOWN",
|
|
86
86
|
"FRONTMATTER_MALFORMED",
|
|
87
87
|
"OPEN_QUESTION",
|
|
88
|
+
"SECTION_PLACEHOLDER_ONLY",
|
|
88
89
|
"STATUS_UNKNOWN",
|
|
89
90
|
"SUPERSESSION_STATE_INCONSISTENT",
|
|
90
91
|
"VERIFIED_IN_CHANGED",
|
|
@@ -252,6 +253,62 @@ def _mechanical_findings(record: Dict) -> List[Dict[str, str]]:
|
|
|
252
253
|
return sorted(findings, key=lambda item: item["code"])
|
|
253
254
|
|
|
254
255
|
|
|
256
|
+
def _record_path(record: Dict, adr_dir: Optional[Path] = None) -> Optional[Path]:
|
|
257
|
+
"""Resolve a record's bare filename against the ADR directory, or None.
|
|
258
|
+
|
|
259
|
+
Records reach readiness with `path` set to a filename and no directory, and
|
|
260
|
+
the test suite passes records whose file does not exist at all. Both are
|
|
261
|
+
normal, so this answers "no path" rather than raising.
|
|
262
|
+
"""
|
|
263
|
+
raw = record.get("path")
|
|
264
|
+
if not raw:
|
|
265
|
+
return None
|
|
266
|
+
path = Path(str(raw))
|
|
267
|
+
if not path.is_absolute() and adr_dir is not None and not path.exists():
|
|
268
|
+
path = Path(adr_dir) / path.name
|
|
269
|
+
return path if path.is_file() else None
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def _placeholder_findings(
|
|
273
|
+
record: Dict, adr_dir: Optional[Path] = None
|
|
274
|
+
) -> List[Dict[str, str]]:
|
|
275
|
+
"""Required sections holding an adr-kit placeholder instead of an answer.
|
|
276
|
+
|
|
277
|
+
A migrated record reaches acceptance with `- TODO: add verifiable
|
|
278
|
+
references.` under `## References` and nothing refuses it: the completeness
|
|
279
|
+
gate treats a placeholder as content by decision, because an imported record
|
|
280
|
+
must not fail a blocking gate on arrival. The record then classifies
|
|
281
|
+
`ready-for-confirmation`, which is a lie about a record nobody has finished
|
|
282
|
+
writing. Saying so here reaches the operator before `adr accept` freezes it,
|
|
283
|
+
and readiness has no power to block, which is the point.
|
|
284
|
+
|
|
285
|
+
Empty sections are deliberately not reported: `bin/adr-lint` already fails
|
|
286
|
+
completeness on those, so acceptance refuses them without help.
|
|
287
|
+
"""
|
|
288
|
+
path = _record_path(record, adr_dir)
|
|
289
|
+
if path is None:
|
|
290
|
+
return []
|
|
291
|
+
try:
|
|
292
|
+
text = path.read_text(encoding="utf-8", errors="replace")
|
|
293
|
+
except OSError:
|
|
294
|
+
return []
|
|
295
|
+
try:
|
|
296
|
+
sections = placeholder_required_sections(text, str(record.get("format", "")))
|
|
297
|
+
except AdrFormatError:
|
|
298
|
+
# 'hybrid' and 'unknown' are legal values of record["format"], and
|
|
299
|
+
# neither resolves to a required-section list. Nothing to say, and
|
|
300
|
+
# raising here would be invisible: bin/adr-guardian swallows the
|
|
301
|
+
# exception and returns 0, so the queue would just go stale.
|
|
302
|
+
return []
|
|
303
|
+
return [
|
|
304
|
+
{
|
|
305
|
+
"code": "SECTION_PLACEHOLDER_ONLY",
|
|
306
|
+
"message": f"## {title} holds a migration placeholder, not an answer.",
|
|
307
|
+
}
|
|
308
|
+
for title in sorted(sections)
|
|
309
|
+
]
|
|
310
|
+
|
|
311
|
+
|
|
255
312
|
def _classification(
|
|
256
313
|
record: Dict,
|
|
257
314
|
mechanical: Sequence[Dict[str, str]],
|
|
@@ -293,6 +350,7 @@ def readiness_for_record(
|
|
|
293
350
|
}
|
|
294
351
|
for question in record.get("open_questions", [])
|
|
295
352
|
]
|
|
353
|
+
human.extend(_placeholder_findings(record, adr_dir))
|
|
296
354
|
# Three booleans used to stand in for quality here, which meant a vague ADR
|
|
297
355
|
# and a sharp one scored identically as long as both had a decision line and
|
|
298
356
|
# a verified_in. The real weighted scorer existed the whole time behind
|
package/bin/adr_schema.py
CHANGED
|
@@ -43,7 +43,7 @@ def _load_sibling(name: str):
|
|
|
43
43
|
|
|
44
44
|
_load_sibling("adr_format")
|
|
45
45
|
|
|
46
|
-
from adr_format import SUPPORTED_PROFILES
|
|
46
|
+
from adr_format import SUPPORTED_PROFILES, adr_status, status_statement
|
|
47
47
|
|
|
48
48
|
FRONTMATTER_FIELD_ORDER = (
|
|
49
49
|
"id",
|
|
@@ -92,8 +92,13 @@ STATUS_SECTION_RE = re.compile(
|
|
|
92
92
|
re.IGNORECASE | re.MULTILINE,
|
|
93
93
|
)
|
|
94
94
|
DATE_RE = re.compile(r"\b(\d{4}-\d{2}-\d{2})\b")
|
|
95
|
-
|
|
96
|
-
|
|
95
|
+
# The optional `[` accepts the link-wrapped form real bodies use:
|
|
96
|
+
# "Superseded by [ADR-124](ADR-124-title.md)". Requiring a bare ADR-NNN meant
|
|
97
|
+
# superseded_by came back None on those records while the status was guessed
|
|
98
|
+
# separately, producing frontmatter that contradicted the prose it was inferred
|
|
99
|
+
# from (issue #118).
|
|
100
|
+
SUPERSEDES_RE = re.compile(r"\bSupersedes\s+\[?ADR-(\d{1,4})\b", re.IGNORECASE)
|
|
101
|
+
SUPERSEDED_BY_RE = re.compile(r"\bSuperseded\s+by\s+\[?ADR-(\d{1,4})\b", re.IGNORECASE)
|
|
97
102
|
|
|
98
103
|
|
|
99
104
|
class FrontmatterError(Exception):
|
|
@@ -207,14 +212,27 @@ def infer_frontmatter(body: str, path: Optional[Path] = None) -> Dict:
|
|
|
207
212
|
title_match = generic_title
|
|
208
213
|
title = title_match.group(1).strip() if title_match else ""
|
|
209
214
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
215
|
+
# The same region the status word was read from, so the date and the
|
|
216
|
+
# successor beside it are recovered from that line rather than from a
|
|
217
|
+
# `## Status` section the record may not have (issue #118).
|
|
218
|
+
status_line = status_statement(body)
|
|
219
|
+
# One reader for the status word, shared with adr-index, adr-judge,
|
|
220
|
+
# adr-lint, adr-retire and adr-watch. It handles the `## Status` heading,
|
|
221
|
+
# the bold-inline `**Status:** X` form and a plain `Status: X` line, and it
|
|
222
|
+
# returns None on anything else.
|
|
223
|
+
#
|
|
224
|
+
# None must stay None. This used to default to "Proposed" whenever the one
|
|
225
|
+
# recognised shape did not match - and `re.match` also returns None for any
|
|
226
|
+
# line starting with `**`, `[` or `-`, so bold and link-wrapped statuses
|
|
227
|
+
# fell through too. `status` is the field that decides whether a decision is
|
|
228
|
+
# binding and injected, so guessing it downgraded Accepted records in
|
|
229
|
+
# silence, with exit 0. Both callers already handle an undetermined status
|
|
230
|
+
# honestly: adr_catalog reports STATUS_UNKNOWN, and migrate_text returns it
|
|
231
|
+
# as an issue and writes nothing (issue #118).
|
|
232
|
+
status_word = adr_status(body)
|
|
233
|
+
status = status_word.capitalize() if status_word else None
|
|
216
234
|
if status not in VALID_STATUSES:
|
|
217
|
-
status =
|
|
235
|
+
status = None
|
|
218
236
|
|
|
219
237
|
date_match = DATE_RE.search(status_line)
|
|
220
238
|
status_date = date_match.group(1) if date_match else None
|
package/package.json
CHANGED
package/scripts/bump-version.py
CHANGED
|
@@ -293,7 +293,14 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
293
293
|
print("Then verify the changes and:")
|
|
294
294
|
print(" git add " + " ".join(staged))
|
|
295
295
|
print(f' git commit -m "chore(release): v{version}"')
|
|
296
|
-
|
|
296
|
+
# Deliberately not "git tag": since ADR-042 the tag is created by
|
|
297
|
+
# release-publish.yml from the merged main commit. Tagging by hand is
|
|
298
|
+
# how v0.55.0 was burned - the tag went on the dev tip, where every
|
|
299
|
+
# version site still read the previous release, and the gate refused to
|
|
300
|
+
# publish a tag that was already public.
|
|
301
|
+
print()
|
|
302
|
+
print(f"Do NOT tag by hand. Open a pull request into main; once it merges,")
|
|
303
|
+
print(f"release-publish.yml creates v{version} on the merge commit and publishes.")
|
|
297
304
|
return 0
|
|
298
305
|
except VersionSiteError as exc:
|
|
299
306
|
print(f"bump-version: {exc}", file=sys.stderr)
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Refuse a CHANGELOG entry appended to a section that has already shipped.
|
|
3
|
+
|
|
4
|
+
`release-publish.yml` publishes a `## [X.Y.Z]` section verbatim as the GitHub
|
|
5
|
+
Release body, `bump-version.py` inserts the next release heading directly under
|
|
6
|
+
the `## [Unreleased]` marker, and `release_phases.py` reads a section from its
|
|
7
|
+
heading to the next `^## [`. Section membership is therefore positional, and a
|
|
8
|
+
bullet written under a released heading is lost twice over: it never reaches the
|
|
9
|
+
next release's notes, and the release that already shipped claims work it does
|
|
10
|
+
not contain. That happened twice, through two separate pull requests, and no
|
|
11
|
+
gate saw it: both diffs carry `### Fixed` as unchanged context, so the fragment
|
|
12
|
+
reads exactly like a correct addition unless you map the line numbers back to
|
|
13
|
+
the nearest `## [` heading.
|
|
14
|
+
|
|
15
|
+
WHY THIS COUNTS BULLETS RATHER THAN COMPARING TEXT. Editing a released section
|
|
16
|
+
is legitimate and this project does it: measured over 59 comparable sections,
|
|
17
|
+
six differ from their tag, and every one is a correction rather than an
|
|
18
|
+
addition -- a wrong count fixed from "Nine" to "Ten", a superseded npm claim
|
|
19
|
+
rewritten, two whitespace reflows, two rewordings. A byte-identity rule would
|
|
20
|
+
fail all six. Comparing bullet text fails four of them too, because a reworded
|
|
21
|
+
first line reads as a new bullet. The count is what separates correcting a
|
|
22
|
+
released note from appending to it.
|
|
23
|
+
|
|
24
|
+
Sections whose tag carries no CHANGELOG.md, and early releases made before the
|
|
25
|
+
tagging convention, cannot be compared at all. They are skipped and counted in
|
|
26
|
+
the output rather than passed silently, because a gate that reports "checked"
|
|
27
|
+
while checking nothing is the failure this whole file exists to prevent.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
from __future__ import annotations
|
|
31
|
+
|
|
32
|
+
import argparse
|
|
33
|
+
import re
|
|
34
|
+
import subprocess
|
|
35
|
+
import sys
|
|
36
|
+
from pathlib import Path
|
|
37
|
+
from typing import Callable, Dict, List, Optional, Tuple
|
|
38
|
+
|
|
39
|
+
ROOT = Path(__file__).resolve().parents[1]
|
|
40
|
+
CHANGELOG = ROOT / "CHANGELOG.md"
|
|
41
|
+
|
|
42
|
+
RELEASE_HEADING = re.compile(r"^## \[(\d+\.\d+\.\d+)\]", re.MULTILINE)
|
|
43
|
+
TOP_LEVEL_BULLET = re.compile(r"^- \S")
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def section(text: str, version: str) -> Optional[str]:
|
|
47
|
+
"""The body under `## [version]`, up to the next release heading.
|
|
48
|
+
|
|
49
|
+
Deliberately the same shape as `release_phases._changelog_section`, because
|
|
50
|
+
a gate that reads a section differently from the tool that publishes it
|
|
51
|
+
would pass exactly the documents that break at release time.
|
|
52
|
+
"""
|
|
53
|
+
match = re.search(
|
|
54
|
+
rf"^## \[{re.escape(version)}\][^\n]*\n(.*?)(?=^## \[|\Z)",
|
|
55
|
+
text,
|
|
56
|
+
re.MULTILINE | re.DOTALL,
|
|
57
|
+
)
|
|
58
|
+
return match.group(1) if match else None
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def bullet_count(section_text: str) -> int:
|
|
62
|
+
"""Top-level list items: the unit an author adds, unlike reflowed prose."""
|
|
63
|
+
return sum(1 for line in section_text.splitlines() if TOP_LEVEL_BULLET.match(line))
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def appended_bullets(section_text: str, published_text: str) -> List[str]:
|
|
67
|
+
"""The bullets present now that were not there at the tag.
|
|
68
|
+
|
|
69
|
+
Returned for the message only. The verdict is the count, so a reworded
|
|
70
|
+
bullet is not reported as an addition; this names the likely culprits by
|
|
71
|
+
taking the ones whose text is new, and falls back to the tail when every
|
|
72
|
+
bullet was reworded.
|
|
73
|
+
"""
|
|
74
|
+
was = [line for line in published_text.splitlines() if TOP_LEVEL_BULLET.match(line)]
|
|
75
|
+
now = [line for line in section_text.splitlines() if TOP_LEVEL_BULLET.match(line)]
|
|
76
|
+
fresh = [line for line in now if line not in was]
|
|
77
|
+
gained = len(now) - len(was)
|
|
78
|
+
return fresh[:gained] if len(fresh) >= gained else now[-gained:]
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def check(
|
|
82
|
+
current: str, published_for: Callable[[str], Optional[str]]
|
|
83
|
+
) -> Tuple[List[Dict[str, object]], int, List[str]]:
|
|
84
|
+
"""Compare every release section against the same section at its tag.
|
|
85
|
+
|
|
86
|
+
`published_for` returns the CHANGELOG.md at tag `vX.Y.Z`, or None when that
|
|
87
|
+
tag is unusable. Injected rather than called directly so the rule can be
|
|
88
|
+
tested without a git history, which the test matrix does not fetch.
|
|
89
|
+
"""
|
|
90
|
+
findings: List[Dict[str, object]] = []
|
|
91
|
+
compared = 0
|
|
92
|
+
skipped: List[str] = []
|
|
93
|
+
for version in RELEASE_HEADING.findall(current):
|
|
94
|
+
published = published_for(version)
|
|
95
|
+
was = section(published, version) if published is not None else None
|
|
96
|
+
now = section(current, version)
|
|
97
|
+
if was is None or now is None:
|
|
98
|
+
skipped.append(version)
|
|
99
|
+
continue
|
|
100
|
+
compared += 1
|
|
101
|
+
if bullet_count(now) > bullet_count(was):
|
|
102
|
+
findings.append(
|
|
103
|
+
{
|
|
104
|
+
"version": version,
|
|
105
|
+
"was": bullet_count(was),
|
|
106
|
+
"now": bullet_count(now),
|
|
107
|
+
"bullets": appended_bullets(now, was),
|
|
108
|
+
}
|
|
109
|
+
)
|
|
110
|
+
return findings, compared, skipped
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _git(*args: str) -> Optional[str]:
|
|
114
|
+
result = subprocess.run(
|
|
115
|
+
["git", *args], capture_output=True, text=True, encoding="utf-8", errors="replace"
|
|
116
|
+
)
|
|
117
|
+
return result.stdout if result.returncode == 0 else None
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _published_from_git(tags: set) -> Callable[[str], Optional[str]]:
|
|
121
|
+
# Two spellings ship in this repository: 65 tags read `v0.56.0` and 14
|
|
122
|
+
# older ones read `adr-kit--v0.1.0`. Resolving only the first silently
|
|
123
|
+
# skipped fourteen comparable sections, which is the same kind of
|
|
124
|
+
# overstated coverage this check exists to prevent.
|
|
125
|
+
def resolve(version: str) -> Optional[str]:
|
|
126
|
+
for tag in (f"v{version}", f"adr-kit--v{version}"):
|
|
127
|
+
if tag in tags:
|
|
128
|
+
published = _git("show", f"{tag}:CHANGELOG.md")
|
|
129
|
+
if published is not None:
|
|
130
|
+
return published
|
|
131
|
+
return None
|
|
132
|
+
|
|
133
|
+
return resolve
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def report(findings, compared, skipped, stream=None) -> None:
|
|
137
|
+
# Resolved here rather than in the signature: a default bound at import
|
|
138
|
+
# time keeps writing to the stream that existed then, which silently
|
|
139
|
+
# bypasses any caller that replaced it.
|
|
140
|
+
stream = sys.stdout if stream is None else stream
|
|
141
|
+
print(
|
|
142
|
+
f"Compared {compared} released CHANGELOG section(s) against their tag; "
|
|
143
|
+
f"skipped {len(skipped)} with no usable tag.",
|
|
144
|
+
file=stream,
|
|
145
|
+
)
|
|
146
|
+
for finding in findings:
|
|
147
|
+
print(
|
|
148
|
+
f"\nFAIL ## [{finding['version']}] gained "
|
|
149
|
+
f"{finding['now'] - finding['was']} bullet(s) since its tag "
|
|
150
|
+
f"({finding['was']} -> {finding['now']}):",
|
|
151
|
+
file=stream,
|
|
152
|
+
)
|
|
153
|
+
for bullet in finding["bullets"]:
|
|
154
|
+
print(f" {bullet[:100]}", file=stream)
|
|
155
|
+
if findings:
|
|
156
|
+
print(
|
|
157
|
+
"\nThat section already shipped. release-publish.yml publishes it "
|
|
158
|
+
"verbatim as the GitHub Release body, so an entry added here is "
|
|
159
|
+
"absent from the next release's notes and falsely claimed by a "
|
|
160
|
+
"release that does not contain it.\nMove these bullets under "
|
|
161
|
+
"## [Unreleased], into the matching ### Added / ### Changed / "
|
|
162
|
+
"### Fixed heading.",
|
|
163
|
+
file=stream,
|
|
164
|
+
)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def main(argv: Optional[List[str]] = None) -> int:
|
|
168
|
+
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
|
169
|
+
parser.add_argument(
|
|
170
|
+
"--changelog", default=str(CHANGELOG), help="CHANGELOG.md to check"
|
|
171
|
+
)
|
|
172
|
+
args = parser.parse_args(argv)
|
|
173
|
+
|
|
174
|
+
listed = _git("tag")
|
|
175
|
+
if listed is None:
|
|
176
|
+
print(
|
|
177
|
+
"git tag failed: this check needs the tags, so the workflow step "
|
|
178
|
+
"running it must check out with fetch-depth: 0.",
|
|
179
|
+
file=sys.stderr,
|
|
180
|
+
)
|
|
181
|
+
return 2
|
|
182
|
+
tags = set(listed.split())
|
|
183
|
+
if not tags:
|
|
184
|
+
print(
|
|
185
|
+
"No tags in this checkout. The check cannot compare anything, and "
|
|
186
|
+
"reporting success would be a lie; check out with fetch-depth: 0.",
|
|
187
|
+
file=sys.stderr,
|
|
188
|
+
)
|
|
189
|
+
return 2
|
|
190
|
+
|
|
191
|
+
current = Path(args.changelog).read_text(encoding="utf-8")
|
|
192
|
+
findings, compared, skipped = check(current, _published_from_git(tags))
|
|
193
|
+
report(findings, compared, skipped)
|
|
194
|
+
return 1 if findings else 0
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
if __name__ == "__main__":
|
|
198
|
+
raise SystemExit(main())
|
|
@@ -14,6 +14,13 @@ once. Every mismatch is reported in one pass.
|
|
|
14
14
|
Usage:
|
|
15
15
|
python scripts/check-release-version.py --expect 0.39.0
|
|
16
16
|
python scripts/check-release-version.py --expect v0.39.0 # leading v is stripped
|
|
17
|
+
python scripts/check-release-version.py --print-canonical # the CHANGELOG version, nothing else
|
|
18
|
+
|
|
19
|
+
`--print-canonical` exists so the release workflow can derive the tag from the
|
|
20
|
+
commit it is standing on (ADR-042) without a second implementation of "what
|
|
21
|
+
version is this". It reads the same registry entry the gate above compares
|
|
22
|
+
against, so the tag and the gate can never disagree about where the version
|
|
23
|
+
lives.
|
|
17
24
|
"""
|
|
18
25
|
from __future__ import annotations
|
|
19
26
|
|
|
@@ -40,13 +47,16 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
40
47
|
parser = argparse.ArgumentParser(description=__doc__)
|
|
41
48
|
parser.add_argument(
|
|
42
49
|
"--expect",
|
|
43
|
-
required=True,
|
|
44
50
|
help="Expected release version (git tag). A leading 'v' is stripped.",
|
|
45
51
|
)
|
|
52
|
+
parser.add_argument(
|
|
53
|
+
"--print-canonical",
|
|
54
|
+
action="store_true",
|
|
55
|
+
help="Print the canonical CHANGELOG version and exit, comparing nothing.",
|
|
56
|
+
)
|
|
46
57
|
args = parser.parse_args(argv)
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
parser.error(f"not a MAJOR.MINOR.PATCH version: {args.expect!r}")
|
|
58
|
+
if not args.print_canonical and not args.expect:
|
|
59
|
+
parser.error("one of --expect or --print-canonical is required")
|
|
50
60
|
|
|
51
61
|
try:
|
|
52
62
|
registry = load_registry(ROOT)
|
|
@@ -54,6 +64,21 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
54
64
|
print(f"check-release-version: {exc}", file=sys.stderr)
|
|
55
65
|
return 1
|
|
56
66
|
|
|
67
|
+
if args.print_canonical:
|
|
68
|
+
canonical = read_canonical(ROOT, registry)
|
|
69
|
+
if not canonical:
|
|
70
|
+
print(
|
|
71
|
+
"check-release-version: the CHANGELOG names no release version",
|
|
72
|
+
file=sys.stderr,
|
|
73
|
+
)
|
|
74
|
+
return 1
|
|
75
|
+
print(canonical)
|
|
76
|
+
return 0
|
|
77
|
+
|
|
78
|
+
expected = args.expect.lstrip("vV").strip()
|
|
79
|
+
if not SEMVER.match(expected):
|
|
80
|
+
parser.error(f"not a MAJOR.MINOR.PATCH version: {args.expect!r}")
|
|
81
|
+
|
|
57
82
|
print(f"Expected release version: {expected}")
|
|
58
83
|
canonical = read_canonical(ROOT, registry)
|
|
59
84
|
mark = "ok" if canonical == expected else "MISMATCH"
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Drive a release end to end, leaving only what a person must do.
|
|
3
|
+
|
|
4
|
+
ADR-042: the release runs from the maintainer's machine, with the maintainer's
|
|
5
|
+
own credentials, because GitHub does not start workflow runs for events caused
|
|
6
|
+
by GITHUB_TOKEN - a pull request a workflow opens never receives the checks
|
|
7
|
+
`main` requires, so it can never merge. The tag is not typed here either:
|
|
8
|
+
`release-publish.yml` creates it from the merged commit and publishes in the
|
|
9
|
+
same run, and this driver only verifies that it landed where it belongs.
|
|
10
|
+
|
|
11
|
+
What stays human: deciding to release and choosing the version, writing the
|
|
12
|
+
release notes, approving the merge, and npm's 2FA. Everything between those is
|
|
13
|
+
mechanical, and mechanical steps performed by hand are what cost v0.55.0 and
|
|
14
|
+
left three npm versions unapproved for a week.
|
|
15
|
+
|
|
16
|
+
Safe to re-run. Each phase asks the repository whether its work is already
|
|
17
|
+
done, so an interrupted release is resumed rather than restarted:
|
|
18
|
+
|
|
19
|
+
python scripts/release.py 0.57.0
|
|
20
|
+
python scripts/release.py 0.57.0 --skip-tests # CI still runs them
|
|
21
|
+
python scripts/release.py 0.57.0 --status # what is left, changing nothing
|
|
22
|
+
python scripts/release.py 0.57.0 --only prepare # one phase
|
|
23
|
+
|
|
24
|
+
docs/RELEASING.md is the specification; the phases mirror its steps in order.
|
|
25
|
+
"""
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
import argparse
|
|
29
|
+
import re
|
|
30
|
+
import sys
|
|
31
|
+
from pathlib import Path
|
|
32
|
+
|
|
33
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
34
|
+
|
|
35
|
+
from release_npm import ( # noqa: E402
|
|
36
|
+
DONE,
|
|
37
|
+
STAGED,
|
|
38
|
+
UNREACHABLE,
|
|
39
|
+
WRONG_LATEST,
|
|
40
|
+
npm_instructions,
|
|
41
|
+
npm_state,
|
|
42
|
+
npm_wrong_latest,
|
|
43
|
+
)
|
|
44
|
+
from release_phases import PHASES, Context, ReleaseError # noqa: E402
|
|
45
|
+
|
|
46
|
+
NPM_LABEL = {
|
|
47
|
+
DONE: "done",
|
|
48
|
+
WRONG_LATEST: "PUBLISHED, but `latest` names another version",
|
|
49
|
+
STAGED: "awaiting your 2FA",
|
|
50
|
+
UNREACHABLE: "npm did not answer; run this again",
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _say(text: str = "") -> None:
|
|
57
|
+
print(text, flush=True)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _status(ctx: Context) -> int:
|
|
61
|
+
_say(f"Release {ctx.tag}: what each phase reports about the repository now.")
|
|
62
|
+
_say()
|
|
63
|
+
for phase in PHASES:
|
|
64
|
+
try:
|
|
65
|
+
state = "done" if phase.done(ctx) else "to do"
|
|
66
|
+
except ReleaseError as exc: # a phase that cannot even answer
|
|
67
|
+
state = f"unknown ({exc})"
|
|
68
|
+
_say(f" step {phase.step} {phase.name:<10} {state}")
|
|
69
|
+
_say(f" step 3a npm {NPM_LABEL[npm_state(ctx)]}")
|
|
70
|
+
_say()
|
|
71
|
+
_say("Nothing was changed.")
|
|
72
|
+
return 0
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def main(argv: list[str] | None = None) -> int:
|
|
76
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
77
|
+
parser.add_argument("version", help="release version, for example 0.57.0")
|
|
78
|
+
parser.add_argument(
|
|
79
|
+
"--only",
|
|
80
|
+
choices=[phase.name for phase in PHASES],
|
|
81
|
+
help="run a single phase, skipping the done-check for it",
|
|
82
|
+
)
|
|
83
|
+
parser.add_argument(
|
|
84
|
+
"--status",
|
|
85
|
+
action="store_true",
|
|
86
|
+
help="report what each phase would do and change nothing",
|
|
87
|
+
)
|
|
88
|
+
parser.add_argument(
|
|
89
|
+
"--skip-tests",
|
|
90
|
+
action="store_true",
|
|
91
|
+
help="skip the local pytest run; the pull request still runs it in CI",
|
|
92
|
+
)
|
|
93
|
+
parser.add_argument(
|
|
94
|
+
"--timeout-min",
|
|
95
|
+
type=int,
|
|
96
|
+
default=45,
|
|
97
|
+
help="how long to wait for a merge or for the publish workflow (default 45)",
|
|
98
|
+
)
|
|
99
|
+
args = parser.parse_args(argv)
|
|
100
|
+
|
|
101
|
+
version = args.version.lstrip("vV").strip()
|
|
102
|
+
if not SEMVER.match(version):
|
|
103
|
+
parser.error(f"not a MAJOR.MINOR.PATCH version: {args.version!r}")
|
|
104
|
+
|
|
105
|
+
ctx = Context(
|
|
106
|
+
version=version,
|
|
107
|
+
skip_tests=args.skip_tests,
|
|
108
|
+
timeout_min=args.timeout_min,
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
if args.status:
|
|
112
|
+
return _status(ctx)
|
|
113
|
+
|
|
114
|
+
phases = [p for p in PHASES if p.name == args.only] if args.only else list(PHASES)
|
|
115
|
+
_say(f"Releasing {ctx.tag}. Re-running this command is safe; finished phases are skipped.")
|
|
116
|
+
_say()
|
|
117
|
+
|
|
118
|
+
for phase in phases:
|
|
119
|
+
label = f"step {phase.step} {phase.name}"
|
|
120
|
+
if not args.only and phase.done(ctx):
|
|
121
|
+
_say(f" {label:<22} already done")
|
|
122
|
+
continue
|
|
123
|
+
_say(f" {label:<22} running")
|
|
124
|
+
try:
|
|
125
|
+
for note in phase.run(ctx):
|
|
126
|
+
_say(f" {note}")
|
|
127
|
+
except ReleaseError as exc:
|
|
128
|
+
_say()
|
|
129
|
+
_say(f"Stopped in {phase.name}:")
|
|
130
|
+
_say()
|
|
131
|
+
_say(str(exc))
|
|
132
|
+
_say()
|
|
133
|
+
_say("Nothing after this phase ran. Fix the above and run the same "
|
|
134
|
+
"command again; the phases that finished will be skipped.")
|
|
135
|
+
return 1
|
|
136
|
+
|
|
137
|
+
_say()
|
|
138
|
+
state = npm_state(ctx)
|
|
139
|
+
|
|
140
|
+
if state == DONE:
|
|
141
|
+
_say(f"npm already serves {ctx.version} as latest.")
|
|
142
|
+
_say()
|
|
143
|
+
_say(f"{ctx.tag} is released and every surface agrees.")
|
|
144
|
+
return 0
|
|
145
|
+
|
|
146
|
+
if state == WRONG_LATEST:
|
|
147
|
+
_say("=" * 72)
|
|
148
|
+
_say("RELEASED, BUT npm SERVES A DIFFERENT VERSION")
|
|
149
|
+
_say("=" * 72)
|
|
150
|
+
_say()
|
|
151
|
+
_say(npm_wrong_latest(ctx))
|
|
152
|
+
return 1
|
|
153
|
+
|
|
154
|
+
if state == UNREACHABLE:
|
|
155
|
+
_say(f"Everything up to npm is done, but npm did not answer, so this "
|
|
156
|
+
f"cannot say whether {ctx.version} is published or still staged. "
|
|
157
|
+
f"Run the same command again once you have a connection.")
|
|
158
|
+
return 1
|
|
159
|
+
|
|
160
|
+
_say("=" * 72)
|
|
161
|
+
_say("ONE THING LEFT, AND ONLY YOU CAN DO IT")
|
|
162
|
+
_say("=" * 72)
|
|
163
|
+
_say()
|
|
164
|
+
_say(npm_instructions(ctx))
|
|
165
|
+
_say()
|
|
166
|
+
_say("Then re-run this command: it will verify the dist-tag and finish.")
|
|
167
|
+
return 0
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
if __name__ == "__main__":
|
|
171
|
+
raise SystemExit(main())
|