@rvdbreemen/adr-kit-opencode 0.56.0 → 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 +3 -3
- package/bin/adr +32 -2
- package/bin/adr-lint +40 -2
- package/bin/adr-migrate +28 -0
- package/bin/adr_format.py +73 -0
- package/bin/adr_guardian_queue.py +15 -1
- package/bin/adr_quality_core.py +19 -2
- package/bin/adr_readiness.py +59 -1
- package/package.json +1 -1
- package/scripts/check-changelog-sections.py +198 -0
- 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
|
@@ -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())
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""The one step of a release npm will not let any tool finish.
|
|
3
|
+
|
|
4
|
+
npm requires proof of presence to publish, so a staged package waits for the
|
|
5
|
+
maintainer's 2FA no matter what drives the release. That makes this the seam
|
|
6
|
+
between what ADR-042 automates and what it deliberately leaves to a person,
|
|
7
|
+
which is why it is its own module rather than an eighth entry in PHASES.
|
|
8
|
+
|
|
9
|
+
The distinction the rest of the driver depends on is between a version that is
|
|
10
|
+
still staged and a version that is published while `latest` names an older
|
|
11
|
+
release. From outside they look the same - `npm install` gives you the wrong
|
|
12
|
+
package either way - but only the second is a fault, and only the second has a
|
|
13
|
+
remedy the maintainer can apply without npm's approval flow.
|
|
14
|
+
"""
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import json
|
|
18
|
+
import sys
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
|
|
21
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
22
|
+
|
|
23
|
+
from release_shell import PACKAGE, Context, run # noqa: E402
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
DONE = "done"
|
|
27
|
+
WRONG_LATEST = "wrong-latest"
|
|
28
|
+
STAGED = "staged"
|
|
29
|
+
UNREACHABLE = "unreachable"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _dist_tags(ctx: Context) -> dict | None:
|
|
33
|
+
"""None means npm did not answer, which is not the same as an empty answer."""
|
|
34
|
+
code, out, _ = run(["npm", "view", PACKAGE, "dist-tags", "--json", "--prefer-online"])
|
|
35
|
+
if code != 0:
|
|
36
|
+
return None
|
|
37
|
+
try:
|
|
38
|
+
parsed = json.loads(out)
|
|
39
|
+
except json.JSONDecodeError:
|
|
40
|
+
return None
|
|
41
|
+
return parsed if isinstance(parsed, dict) else None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def npm_state(ctx: Context) -> str:
|
|
45
|
+
"""Which of the four things npm is currently doing about this version.
|
|
46
|
+
|
|
47
|
+
Deciding this in one place is what keeps the driver's report and its exit
|
|
48
|
+
code from disagreeing, which is the defect this function replaced: the
|
|
49
|
+
predicate existed and nothing wired it to a failure.
|
|
50
|
+
|
|
51
|
+
A registry that does not answer gets its own state rather than being folded
|
|
52
|
+
into one of the others. Reporting "awaiting your 2FA" because npm was down
|
|
53
|
+
would be a guess presented as a reading, and it is the reading a maintainer
|
|
54
|
+
would act on.
|
|
55
|
+
"""
|
|
56
|
+
tags = _dist_tags(ctx)
|
|
57
|
+
if tags is None:
|
|
58
|
+
return UNREACHABLE
|
|
59
|
+
if tags.get("latest") == ctx.version:
|
|
60
|
+
return DONE
|
|
61
|
+
return WRONG_LATEST if npm_published(ctx) else STAGED
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def npm_published(ctx: Context) -> bool:
|
|
65
|
+
"""Is the version on the registry at all, whatever `latest` points at?
|
|
66
|
+
|
|
67
|
+
This separates the two npm states that look identical from outside. A
|
|
68
|
+
version still staged is a release waiting on the maintainer's 2FA, which is
|
|
69
|
+
the normal end of a release rather than a fault. A version that IS
|
|
70
|
+
published while `latest` names an older release is the v0.55.1 defect:
|
|
71
|
+
`npm install` quietly serves the wrong package. Only the second is a
|
|
72
|
+
failure, and telling the maintainer to go and approve something that is
|
|
73
|
+
already approved sends them to the one place that cannot fix it.
|
|
74
|
+
"""
|
|
75
|
+
code, out, _ = run(["npm", "view", PACKAGE, "versions", "--json", "--prefer-online"])
|
|
76
|
+
if code != 0:
|
|
77
|
+
return False
|
|
78
|
+
try:
|
|
79
|
+
versions = json.loads(out)
|
|
80
|
+
except json.JSONDecodeError:
|
|
81
|
+
return False
|
|
82
|
+
if isinstance(versions, str): # npm returns a bare string for a lone version
|
|
83
|
+
versions = [versions]
|
|
84
|
+
return isinstance(versions, list) and ctx.version in versions
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def npm_wrong_latest(ctx: Context) -> str:
|
|
88
|
+
latest = (_dist_tags(ctx) or {}).get("latest") or "nothing this driver could read"
|
|
89
|
+
return (
|
|
90
|
+
f"{ctx.version} is published on npm, but `latest` names {latest}.\n\n"
|
|
91
|
+
f"`npm install {PACKAGE}` therefore serves {latest} rather than the "
|
|
92
|
+
f"release. npm sets `latest` to the version published LAST, not the "
|
|
93
|
+
f"highest, so approving staged versions out of order does exactly "
|
|
94
|
+
f"this. It left 0.55.1 released while `latest` read 0.54.0 for a "
|
|
95
|
+
f"week, and nothing surfaced it.\n\n"
|
|
96
|
+
f" npm dist-tag add {PACKAGE}@{ctx.version} latest\n"
|
|
97
|
+
f" npm dist-tag ls {PACKAGE} # latest must read {ctx.version}\n\n"
|
|
98
|
+
f"Read the first command's own exit code. Piping it into `tail` "
|
|
99
|
+
f"reports tail's status instead, and npm's failure disappears."
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def npm_instructions(ctx: Context) -> str:
|
|
104
|
+
return (
|
|
105
|
+
f"The OpenCode package for {ctx.tag} is STAGED, not published. npm "
|
|
106
|
+
f"requires proof of presence, so no tool can finish this.\n\n"
|
|
107
|
+
f" npm login\n"
|
|
108
|
+
f" npm stage list {PACKAGE}\n"
|
|
109
|
+
f" npm stage view <stage-id> # inspect the tarball first\n"
|
|
110
|
+
f" npm stage approve <stage-id> # prompts for your OTP\n\n"
|
|
111
|
+
f" or from the browser: https://www.npmjs.com/staged-packages\n\n"
|
|
112
|
+
f"If more than one version is staged, approve them in ASCENDING order. "
|
|
113
|
+
f"npm sets `latest` to the version published LAST, not the highest. On "
|
|
114
|
+
f"2026-08-26 approving 0.55.1, then 0.53.0, then 0.54.0 left `latest` on "
|
|
115
|
+
f"0.54.0 while 0.55.1 was the release.\n\n"
|
|
116
|
+
f" npm dist-tag ls {PACKAGE} # latest must read {ctx.version}"
|
|
117
|
+
)
|
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""The phases of docs/RELEASING.md, each one able to say whether it is already done.
|
|
3
|
+
|
|
4
|
+
ADR-042 makes this the sanctioned way to cut a release, and keeps
|
|
5
|
+
docs/RELEASING.md as the specification: every phase here mirrors one step
|
|
6
|
+
there, in the same order, so a divergence between the two is visible in review
|
|
7
|
+
rather than hidden.
|
|
8
|
+
|
|
9
|
+
Every phase is idempotent. A release that dies halfway is the normal case - a
|
|
10
|
+
check goes red, a merge waits on CI, a machine is closed - and the recovery has
|
|
11
|
+
to be "run it again", not "work out which half already happened". Each phase
|
|
12
|
+
answers `done(ctx)` from the repository's actual state rather than from a
|
|
13
|
+
progress file, because a progress file is one more thing that can disagree with
|
|
14
|
+
reality.
|
|
15
|
+
|
|
16
|
+
`verify_tag` exists because nothing checked it before and its absence cost a
|
|
17
|
+
release: it asserts the tag resolves to `origin/main`. v0.55.0 was burned by a
|
|
18
|
+
tag on the dev tip, where every version site still read the previous release,
|
|
19
|
+
and the gate correctly refused to publish it.
|
|
20
|
+
|
|
21
|
+
The npm step is not a phase and lives in release_npm.py. It is the one part of
|
|
22
|
+
a release no tool may finish, so it sits on the other side of ADR-042's
|
|
23
|
+
automation boundary rather than inside PHASES.
|
|
24
|
+
"""
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import json
|
|
28
|
+
import re
|
|
29
|
+
import sys
|
|
30
|
+
from pathlib import Path
|
|
31
|
+
from typing import Callable, List, NamedTuple, Tuple
|
|
32
|
+
|
|
33
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
34
|
+
|
|
35
|
+
from release_shell import ( # noqa: E402
|
|
36
|
+
CLIENTS,
|
|
37
|
+
PACKAGE,
|
|
38
|
+
ROOT,
|
|
39
|
+
Context,
|
|
40
|
+
ReleaseError,
|
|
41
|
+
_clean_tree,
|
|
42
|
+
_client_version,
|
|
43
|
+
_main_sha,
|
|
44
|
+
_version_everywhere,
|
|
45
|
+
_wait_until,
|
|
46
|
+
git,
|
|
47
|
+
run,
|
|
48
|
+
script,
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
# --- phase 0: preflight -----------------------------------------------------
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def preflight_done(ctx: Context) -> bool:
|
|
56
|
+
return False # cheap, and its answer can change between runs
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def preflight(ctx: Context) -> List[str]:
|
|
60
|
+
notes = []
|
|
61
|
+
if not _clean_tree():
|
|
62
|
+
raise ReleaseError(
|
|
63
|
+
"the working tree has uncommitted changes. Commit or stash them "
|
|
64
|
+
"first: a release commit must contain the version bump and nothing "
|
|
65
|
+
"that happened to be lying around."
|
|
66
|
+
)
|
|
67
|
+
code, out, _ = script("check-branch-sync.py")
|
|
68
|
+
if code == 1:
|
|
69
|
+
raise ReleaseError(
|
|
70
|
+
"dev does not carry every published release:\n"
|
|
71
|
+
+ out
|
|
72
|
+
+ "\nMerge main back into dev and land that first. A release branch "
|
|
73
|
+
"cut from a stale dev collides with main on every version stamp."
|
|
74
|
+
)
|
|
75
|
+
if code == 2:
|
|
76
|
+
notes.append("branch-sync check could not run; treated as infrastructure noise")
|
|
77
|
+
if run(["gh", "auth", "status"])[0] != 0:
|
|
78
|
+
raise ReleaseError(
|
|
79
|
+
"gh is not authenticated. The driver opens the pull request with "
|
|
80
|
+
"your credentials on purpose: GitHub does not start workflow runs "
|
|
81
|
+
"for events caused by GITHUB_TOKEN, so a bot-opened PR would never "
|
|
82
|
+
"receive the checks main requires (ADR-042)."
|
|
83
|
+
)
|
|
84
|
+
notes.append("working tree clean, dev current, gh authenticated")
|
|
85
|
+
return notes
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
# --- phase 1: prepare the version and the release notes ---------------------
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def prepare_done(ctx: Context) -> bool:
|
|
92
|
+
return _version_everywhere(ctx) and not _changelog_is_placeholder(ctx)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _changelog_section(ctx: Context) -> str:
|
|
96
|
+
text = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
|
|
97
|
+
match = re.search(
|
|
98
|
+
rf"^## \[{re.escape(ctx.version)}\][^\n]*\n(.*?)(?=^## \[|\Z)",
|
|
99
|
+
text,
|
|
100
|
+
re.MULTILINE | re.DOTALL,
|
|
101
|
+
)
|
|
102
|
+
return match.group(1) if match else ""
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _changelog_is_placeholder(ctx: Context) -> bool:
|
|
106
|
+
"""Is this section still the stub `bump-version.py` wrote, or empty?
|
|
107
|
+
|
|
108
|
+
Matched on the placeholder's SHAPE, a top-level `- TODO:` list item, rather
|
|
109
|
+
than on the word anywhere in the section. The substring test blocked 0.57.0,
|
|
110
|
+
whose notes describe the placeholder-detection work of TASK-198 and TASK-199
|
|
111
|
+
and therefore quote `- TODO:` markers five times, none of them a placeholder.
|
|
112
|
+
A gate that cannot let a release describe its own subject matter leaves the
|
|
113
|
+
author no move except degrading the notes.
|
|
114
|
+
|
|
115
|
+
Still catches a leftover TODO item an author wrote themselves, which
|
|
116
|
+
comparing against `bump-version.py`'s exact string would miss.
|
|
117
|
+
"""
|
|
118
|
+
body = _changelog_section(ctx)
|
|
119
|
+
return (not body.strip()) or any(
|
|
120
|
+
line.strip().startswith("- TODO:") for line in body.splitlines()
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def prepare(ctx: Context) -> List[str]:
|
|
125
|
+
notes = []
|
|
126
|
+
if not _version_everywhere(ctx):
|
|
127
|
+
_, out, _ = script("bump-version.py", ctx.version, check=True)
|
|
128
|
+
notes.append(out.strip().splitlines()[0] if out.strip() else "version written")
|
|
129
|
+
script("build-client-adapters.py", check=True)
|
|
130
|
+
notes.append("client adapters regenerated")
|
|
131
|
+
if _changelog_is_placeholder(ctx):
|
|
132
|
+
raise ReleaseError(
|
|
133
|
+
f"CHANGELOG.md's [{ctx.version}] section is still the placeholder.\n"
|
|
134
|
+
"release-publish.yml publishes that section verbatim as the GitHub "
|
|
135
|
+
"Release body, so it has to read as the announcement: group the "
|
|
136
|
+
"changes, name the user-facing impact, call out upgrade steps.\n"
|
|
137
|
+
"Write it, then run this command again - everything else is already "
|
|
138
|
+
"in place."
|
|
139
|
+
)
|
|
140
|
+
notes.append(f"every version site reads {ctx.version}")
|
|
141
|
+
return notes
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
# --- phase 2: the gates CI will run anyway ----------------------------------
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def verify_done(ctx: Context) -> bool:
|
|
148
|
+
return False # the point is to run them
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def verify(ctx: Context) -> List[str]:
|
|
152
|
+
notes = []
|
|
153
|
+
for label, cmd in (
|
|
154
|
+
("version consistency", lambda: script("check-release-version.py", "--expect", ctx.tag)),
|
|
155
|
+
("adapter drift", lambda: script("build-client-adapters.py", "--check")),
|
|
156
|
+
):
|
|
157
|
+
if cmd()[0] != 0:
|
|
158
|
+
raise ReleaseError(f"{label} check failed; run it directly to see the detail")
|
|
159
|
+
notes.append(f"{label}: pass")
|
|
160
|
+
for label, cmd in (
|
|
161
|
+
("adr-lint --strict", ["bin/adr-lint", "--strict", "docs/adr"]),
|
|
162
|
+
("adr-index --check", ["bin/adr-index", "--check", "docs/adr"]),
|
|
163
|
+
):
|
|
164
|
+
if run([sys.executable, str(ROOT / cmd[0]), *cmd[1:]])[0] != 0:
|
|
165
|
+
raise ReleaseError(f"{label} failed; run it directly to see the detail")
|
|
166
|
+
notes.append(f"{label}: pass")
|
|
167
|
+
if ctx.skip_tests:
|
|
168
|
+
notes.append("pytest SKIPPED by request; CI still runs it on the pull request")
|
|
169
|
+
return notes
|
|
170
|
+
code, out, _ = run([sys.executable, "-m", "pytest", "-q", "-p", "no:cacheprovider"])
|
|
171
|
+
tail = (out.strip().splitlines() or ["no output"])[-1]
|
|
172
|
+
if code != 0:
|
|
173
|
+
raise ReleaseError(
|
|
174
|
+
f"the test suite failed: {tail}\n"
|
|
175
|
+
"Before treating this as real, check that no second pytest is "
|
|
176
|
+
"running: a killed background wrapper leaves its child alive, and "
|
|
177
|
+
"two concurrent runs produce failures that are artefacts."
|
|
178
|
+
)
|
|
179
|
+
notes.append(f"pytest: {tail}")
|
|
180
|
+
return notes
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
# --- phase 3: land on main --------------------------------------------------
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def land_done(ctx: Context) -> bool:
|
|
187
|
+
git("fetch", "origin", "--tags")
|
|
188
|
+
code, head, _ = git("show", "origin/main:CHANGELOG.md")
|
|
189
|
+
if code != 0:
|
|
190
|
+
return False
|
|
191
|
+
return bool(re.search(rf"^## \[{re.escape(ctx.version)}\]", head, re.MULTILINE))
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def land(ctx: Context) -> List[str]:
|
|
195
|
+
notes = []
|
|
196
|
+
current = git("rev-parse", "--abbrev-ref", "HEAD")[1].strip()
|
|
197
|
+
if current != ctx.branch:
|
|
198
|
+
if git("rev-parse", "--verify", ctx.branch)[0] == 0:
|
|
199
|
+
git("checkout", ctx.branch, check=True)
|
|
200
|
+
else:
|
|
201
|
+
git("checkout", "-b", ctx.branch, check=True)
|
|
202
|
+
notes.append(f"on {ctx.branch}")
|
|
203
|
+
if not _clean_tree():
|
|
204
|
+
git("add", "-A", check=True)
|
|
205
|
+
git("commit", "-m", f"chore(release): {ctx.tag}", check=True)
|
|
206
|
+
notes.append("release commit written")
|
|
207
|
+
git("push", "-u", "origin", ctx.branch, check=True)
|
|
208
|
+
|
|
209
|
+
existing = run(["gh", "pr", "list", "--head", ctx.branch, "--json", "number", "--jq", ".[0].number"])[1].strip()
|
|
210
|
+
if not existing:
|
|
211
|
+
body = (
|
|
212
|
+
f"Release {ctx.tag}. Prepared by `scripts/release.py`, which mirrors "
|
|
213
|
+
f"`docs/RELEASING.md`.\n\n"
|
|
214
|
+
f"**Do not tag this by hand.** Since ADR-042 `release-publish.yml` "
|
|
215
|
+
f"creates the tag from the merged commit and publishes in the same "
|
|
216
|
+
f"run. Tagging by hand is how v0.55.0 was burned.\n\n"
|
|
217
|
+
f"Release notes are the `## [{ctx.version}]` CHANGELOG section, which "
|
|
218
|
+
f"the workflow publishes verbatim."
|
|
219
|
+
)
|
|
220
|
+
run(["gh", "pr", "create", "--base", "main", "--head", ctx.branch,
|
|
221
|
+
"--title", f"chore(release): {ctx.tag}", "--body", body], check=True)
|
|
222
|
+
notes.append("pull request opened into main")
|
|
223
|
+
number = run(["gh", "pr", "list", "--head", ctx.branch, "--json", "number", "--jq", ".[0].number"])[1].strip()
|
|
224
|
+
run(["gh", "pr", "merge", number, "--auto", "--merge"])
|
|
225
|
+
notes.append(f"auto-merge armed on #{number}; waiting for the required checks")
|
|
226
|
+
_wait_until(lambda: land_done(ctx), ctx, f"pull request #{number} to merge into main")
|
|
227
|
+
notes.append("merged into main")
|
|
228
|
+
return notes
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
# --- phase 4: the tag the workflow creates ----------------------------------
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def verify_tag_done(ctx: Context) -> bool:
|
|
235
|
+
git("fetch", "origin", "--tags")
|
|
236
|
+
peeled = git("rev-parse", f"{ctx.tag}^{{}}")
|
|
237
|
+
return peeled[0] == 0 and peeled[1].strip() == _main_sha()
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def verify_tag(ctx: Context) -> List[str]:
|
|
241
|
+
_wait_until(lambda: git("rev-parse", f"{ctx.tag}^{{}}")[0] == 0, ctx,
|
|
242
|
+
f"release-publish.yml to create {ctx.tag}")
|
|
243
|
+
peeled = git("rev-parse", f"{ctx.tag}^{{}}")[1].strip()
|
|
244
|
+
main = _main_sha()
|
|
245
|
+
if peeled != main:
|
|
246
|
+
raise ReleaseError(
|
|
247
|
+
f"{ctx.tag} resolves to {peeled[:7]} but origin/main is {main[:7]}.\n"
|
|
248
|
+
"A tag on a commit whose version sites disagree with it is exactly "
|
|
249
|
+
"what cost v0.55.0. Do not move the tag: a pushed tag is a public "
|
|
250
|
+
"ref consumers may register a marketplace from. Release the next "
|
|
251
|
+
"patch version instead."
|
|
252
|
+
)
|
|
253
|
+
return [f"{ctx.tag} resolves to {peeled[:7]}, equal to origin/main"]
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
# --- phase 5: merge back into dev -------------------------------------------
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def syncback_done(ctx: Context) -> bool:
|
|
260
|
+
return script("check-branch-sync.py")[0] == 0
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def syncback(ctx: Context) -> List[str]:
|
|
264
|
+
branch = f"sync/{ctx.tag}-to-dev"
|
|
265
|
+
git("fetch", "origin")
|
|
266
|
+
if git("rev-parse", "--verify", branch)[0] != 0:
|
|
267
|
+
git("checkout", "-b", branch, "origin/dev", check=True)
|
|
268
|
+
else:
|
|
269
|
+
git("checkout", branch, check=True)
|
|
270
|
+
code, out, err = git("merge", "origin/main", "--no-edit")
|
|
271
|
+
if code != 0:
|
|
272
|
+
raise ReleaseError(
|
|
273
|
+
"the merge back into dev has conflicts:\n" + out + err +
|
|
274
|
+
"\nResolve them with main authoritative for anything a release "
|
|
275
|
+
"touches - version sites, generated adapters, manifests, the "
|
|
276
|
+
"OpenCode package - and keep dev's [Unreleased] entries above "
|
|
277
|
+
"main's published sections in CHANGELOG.md. Then run this again."
|
|
278
|
+
)
|
|
279
|
+
git("push", "-u", "origin", branch, check=True)
|
|
280
|
+
if not run(["gh", "pr", "list", "--head", branch, "--json", "number", "--jq", ".[0].number"])[1].strip():
|
|
281
|
+
run(["gh", "pr", "create", "--base", "dev", "--head", branch,
|
|
282
|
+
"--title", f"Merge the published {ctx.tag} release back into dev",
|
|
283
|
+
"--body", "Step 5 of docs/RELEASING.md. Skipping it is silent at "
|
|
284
|
+
"the time and arms the next release to revert this one."], check=True)
|
|
285
|
+
number = run(["gh", "pr", "list", "--head", branch, "--json", "number", "--jq", ".[0].number"])[1].strip()
|
|
286
|
+
run(["gh", "pr", "merge", number, "--auto", "--merge"])
|
|
287
|
+
return [f"sync pull request #{number} opened and armed"]
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
# --- phase 6: this machine's prepared-directory marketplace -----------------
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
def install_done(ctx: Context) -> bool:
|
|
295
|
+
return all(_client_version(name) == ctx.version for name in CLIENTS)
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
def install(ctx: Context) -> List[str]:
|
|
299
|
+
run([sys.executable, str(ROOT / "scripts" / "install-agent-envs.py"), "--clients", "all"])
|
|
300
|
+
# The exit code is not the answer: read each client back. A rollback that
|
|
301
|
+
# cannot validate reports failure while leaving the install intact, and an
|
|
302
|
+
# install that reports success can still be blocked on one client.
|
|
303
|
+
reported = {name: _client_version(name) for name in CLIENTS}
|
|
304
|
+
behind = [f"{n}={v or 'unreadable'}" for n, v in reported.items() if v != ctx.version]
|
|
305
|
+
if behind:
|
|
306
|
+
raise ReleaseError(
|
|
307
|
+
"these clients do not report the released version: " + ", ".join(behind) + "\n"
|
|
308
|
+
"On Windows a client that is running holds its own plugin directory: "
|
|
309
|
+
"an MCP server started with a relative command has that directory as "
|
|
310
|
+
"its working directory, which locks it. Close the client, confirm no "
|
|
311
|
+
"adr-mcp process survives it, then run this command again."
|
|
312
|
+
)
|
|
313
|
+
return [f"all three clients report {ctx.version}"]
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
class Phase(NamedTuple):
|
|
317
|
+
name: str
|
|
318
|
+
step: str
|
|
319
|
+
done: Callable[[Context], bool]
|
|
320
|
+
run: Callable[[Context], List[str]]
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
PHASES: Tuple[Phase, ...] = (
|
|
324
|
+
Phase("preflight", "0", preflight_done, preflight),
|
|
325
|
+
Phase("prepare", "1", prepare_done, prepare),
|
|
326
|
+
Phase("verify", "2", verify_done, verify),
|
|
327
|
+
Phase("land", "3", land_done, land),
|
|
328
|
+
Phase("tag", "3", verify_tag_done, verify_tag),
|
|
329
|
+
Phase("syncback", "4", syncback_done, syncback),
|
|
330
|
+
Phase("install", "6", install_done, install),
|
|
331
|
+
)
|