Skip to content

Commit c27b24c

Browse files
chore: prepare 0.24.0-alpha.7 release
1 parent 4c11900 commit c27b24c

13 files changed

Lines changed: 381 additions & 12 deletions

File tree

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: release-notes
3+
description: Draft and review Python Agents SDK release notes with highlights first. Use for alpha or stable release preparation, changelog audits, and release-note revisions before publication.
4+
---
5+
6+
# Release notes
7+
8+
Turn the verified release diff into customer-facing notes, then return the complete draft for review. Follow the [release procedure](../../../.github/RELEASING.md) for the current branch. This skill drafts release copy; it does not publish, tag, upload packages, or approve a release.
9+
10+
## Establish the release range
11+
12+
Record the repository, release channel, proposed version, target commit, and previous published release. Resolve branch names to commits so the draft describes a fixed range. Honor a supplied version or baseline after verifying it; otherwise propose the next version from the current source metadata and published history.
13+
14+
Choose the previous **published release in the same channel that is reachable from the target**. Verify its remote tag, commit, and publication state. Do not use the newest tag across all branches, a local-only tag, or GitHub's stable-only `releases/latest` endpoint for an alpha. If publication evidence is missing, label the baseline provisional and keep that uncertainty in the review handoff.
15+
16+
On public `feat/codex-harness`, use `CHANGELOG-alpha.md`. Keep stable `CHANGELOG.md` and historical entries intact. The legacy private-preview preparation and review skills do not apply to this public branch. Read [automation integration](references/automation.md) when preparing files for a release command or an existing release workflow.
17+
18+
## Audit the changes
19+
20+
Read the full commit range, changed-file list, and current changelog entries. Inspect the relevant source, tests, and documentation for each customer-visible claim. Check the final target behavior: a feature added and then removed or renamed within the range is not two release features.
21+
22+
Include new capabilities, meaningful fixes, performance changes, changed defaults, and API or durable-state compatibility changes. Group related commits by what users can do. Exclude internal refactors, test-only work, and release housekeeping unless they change installation, supported platforms, or another customer workflow. Cover changes in the bundled native runtime when the release changes it.
23+
24+
For upgrade actions, compare the published baseline with the target. State the old behavior, the new behavior, and the supported replacement. Preserve exact API names, defaults, platform limits, experimental status, and opt-ins. Do not invent migration support or claim that tests or package builds passed without evidence.
25+
26+
Keep a short local evidence map from each theme to commits, PRs, or source paths. Record meaningful exclusions there. Keep that audit and internal release assessment out of the public notes.
27+
28+
## Write the draft
29+
30+
Use this order, omitting empty sections:
31+
32+
1. Release title. Add an introduction only when it provides useful context beyond the title and highlights.
33+
2. **Highlights**: usually three to five bullets explaining the most useful changes. A small release can have fewer. Lead each bullet with the capability or benefit, then one concrete sentence. Include the most important compatibility warning here when it affects adoption.
34+
3. **Upgrading from <previous version>**: required user actions and changed defaults before the detailed list.
35+
4. **Added**, **Changed**, and **Fixed**: concise details grouped by user impact, not commit order. Use only relevant categories; avoid repeating each highlight verbatim.
36+
37+
Do not add an Installation section by default. Keep routine setup commands, platform tables, checksums, and import checks in the installation guide. Include installation details only when explicitly requested or when this release changes how users install the SDK; place those release-specific actions under Upgrading. A single guide link is optional when it helps the reader act.
38+
39+
Order bullets within every section by customer impact. Use reliable customer-request evidence when it is available; otherwise use breadth of use, upgrade risk, and practical value. Prioritize adoption and production capabilities in Highlights and Added, required or broadly relevant actions in Upgrading, and security or data-integrity fixes in Fixed. Put narrow opt-ins and experimental integrations later. Do not claim that an item is most requested without evidence.
40+
41+
Use verified native PR references or documentation links where they help the reader act. Follow the repository's copy-ready GitHub formatting rules. Prefer published documentation or files at the pinned target commit; do not link to an open PR or a moving feature branch as if it described the released package. Do not add PR numbers or attribution that has not been verified.
42+
43+
Write customer-facing notes as they should read when published. Use present tense for any installation or download text included at the user's request or because of a release-specific change. Keep draft labels, unpublished status, and warnings about proposed URLs in the maintainer handoff or the chat introduction, outside the copy-ready notes. Use the distribution route required by the release procedure; public alpha wheels come from GitHub Releases. Verify the final version and filenames against qualified artifacts before publication. Keep pending checks and the detailed readiness assessment in the handoff; do not invent completed verification. The final public verification footer may identify the exact source and qualifying Tests run.
44+
45+
## Review before publication
46+
47+
Show the **complete draft**, including the proposed highlights, before any release publication. Do not require a separate approval just to write the highlights. Ask for review of the concrete result, and preserve any publication authorization already given by the user. Approval of wording does not grant unrelated repository or publishing actions.
48+
49+
Record which target commit and draft the user reviewed. A changed release range or a substantive edit requires review of the updated notes before publication. Updating a verified CI link or another factual release receipt does not require another editorial round unless it changes the release claims.
50+
51+
After review, pass the reviewed text to the existing release procedure. Keep the exact source, version, and artifact checks in that procedure. Do not substitute local wheels, mark an alpha as latest stable, or enable a disabled publisher. Return the draft path, release range, unresolved claims or qualification gaps, and the next required action.
52+
53+
This workflow adapts Pi's [changelog audit prompt](https://github.com/earendil-works/pi/blob/v1.5.0/.pi/prompts/cl.md): audit the diff, select the most useful changes, and put highlights before the detailed changelog.
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Connect release notes to preparation
2+
3+
The skill writes the customer-facing copy. Existing release tools own version changes, artifact qualification, and publication. Keep these responsibilities separate so drafting cannot publish a release.
4+
5+
## Public v1 alpha
6+
7+
Use the current [release procedure](../../../../.github/RELEASING.md). Start the draft before preparing the version commit. Save the authored copy outside the source tree, for example as `$RELEASE_STAGE/authored-notes.md`. Record its previous published tag and target commit in the maintainer handoff.
8+
9+
After the candidate's Tests run passes, use the existing `qualify-distributions` command to produce `$RELEASE_STAGE/qualification.json`. Audit any changes between the draft's target and the qualified candidate. Update the copy for that exact version. Keep routine installation commands and platform details in the installation guide, not the release notes; verify any included download link against the qualified wheel filenames. Write customer copy for the moment of publication from the first draft; keep draft labels, unpublished status, and pending download checks in the separate review handoff. Leave `Release verification` out of the authored copy; the helper adds it.
10+
11+
Assemble the complete file for human review:
12+
13+
```sh
14+
python .agents/skills/release-notes/scripts/prepare_notes.py \
15+
--notes "$RELEASE_STAGE/authored-notes.md" \
16+
--qualification "$RELEASE_STAGE/qualification.json" \
17+
--version "${RELEASE_TAG#v}" \
18+
--source-sha "$RELEASE_SHA" \
19+
--output "$RELEASE_STAGE/notes.md"
20+
```
21+
22+
The helper checks that the authored title, requested version and source, and local qualification record agree. It requires Highlights first and adds canonical source and Tests links. It creates a new file without replacing the authored copy or an earlier review draft. Use a new output filename when revising it.
23+
24+
This is a local consistency check, not a new CI qualification or proof of human approval. Use the record produced by the existing qualifier, not a hand-written substitute. The helper uses no network, credentials, model API, or publishing command.
25+
26+
Show the complete generated file and resolve substantive feedback before publication. Then the existing `gh release create --notes-file` command consumes that same reviewed file, subject to the release procedure's current source, artifact, and authorization checks. Adding the successful post-publication installation run follows that procedure.
27+
28+
## Existing main automation
29+
30+
`release-please.yml`, `release-candidate.yml`, and the release-readiness controller target `main`. The `publish-notes` command appends a human-approved release assessment after publication; it is not a prepublication authoring step. Do not feed this customer-copy file into that assessment's approval marker or treat the two documents as interchangeable.
31+
32+
The writing skill can supply highlights and changelog text during a main release's preparation. Its local assembly helper currently supports only public alpha qualification records. It does not enable the PyPI publisher, change main's review checks, or reactivate the historical private-preview skills. Any future automatic drafting job should produce a reviewable artifact before publication and use this skill as its writing instructions.
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
#!/usr/bin/env python3
2+
"""Assemble alpha notes for review from authored copy and an existing qualification."""
3+
4+
from __future__ import annotations
5+
6+
import argparse
7+
import json
8+
import re
9+
from pathlib import Path
10+
from typing import Any
11+
12+
REPOSITORY = "openai/openai-agents-python"
13+
14+
15+
def assemble_notes(
16+
notes: str, qualification: dict[str, Any], *, version: str, source_sha: str
17+
) -> str:
18+
"""Check local record consistency; do not requalify CI or approve publication."""
19+
if not re.fullmatch(r"\d+\.\d+\.\d+-alpha\.\d+", version):
20+
raise ValueError("Expected a source version such as 0.24.0-alpha.7")
21+
if not re.fullmatch(r"[0-9a-f]{40}", source_sha):
22+
raise ValueError("Expected the full source commit SHA")
23+
if not isinstance(qualification, dict) or qualification.get("version") != version:
24+
raise ValueError("Qualification version does not match the requested release")
25+
run = qualification.get("run")
26+
if not isinstance(run, dict) or run.get("head_sha") != source_sha:
27+
raise ValueError("Qualification source does not match the requested commit")
28+
if (
29+
(run.get("repository") or {}).get("full_name") != REPOSITORY
30+
or (run.get("head_repository") or {}).get("full_name") != REPOSITORY
31+
or run.get("head_branch") != "feat/codex-harness"
32+
or run.get("path") != ".github/workflows/tests.yml"
33+
or run.get("event") != "push"
34+
or run.get("status") != "completed"
35+
or run.get("conclusion") != "success"
36+
or type(run.get("id")) is not int
37+
or run["id"] <= 0
38+
):
39+
raise ValueError("Expected a successful Tests push run from the public preview branch")
40+
41+
body = notes.strip()
42+
if not body or body.splitlines()[0] != f"# Agents SDK v{version}":
43+
raise ValueError("Notes must start with the exact Agents SDK release title")
44+
sections = re.findall(r"^## (.+)$", body, flags=re.MULTILINE)
45+
if not sections or sections[0] != "Highlights":
46+
raise ValueError("Highlights must be the first level-two section")
47+
if "Release verification" in sections:
48+
raise ValueError("Remove the old Release verification section before assembling notes")
49+
50+
return (
51+
body
52+
+ "\n\n## Release verification\n\n"
53+
+ f"Source: [`{source_sha}`](https://github.com/{REPOSITORY}/commit/{source_sha}).\n\n"
54+
+ f"Built and tested by [Tests #{run['id']}]"
55+
+ f"(https://github.com/{REPOSITORY}/actions/runs/{run['id']}).\n"
56+
)
57+
58+
59+
def main() -> None:
60+
parser = argparse.ArgumentParser(description=__doc__)
61+
parser.add_argument("--notes", required=True, type=Path, help="Authored customer-facing notes")
62+
parser.add_argument("--qualification", required=True, type=Path)
63+
parser.add_argument("--version", required=True, help="Source spelling, without a leading v")
64+
parser.add_argument("--source-sha", required=True)
65+
parser.add_argument(
66+
"--output", required=True, type=Path, help="New file to review before publishing"
67+
)
68+
args = parser.parse_args()
69+
try:
70+
notes = assemble_notes(
71+
args.notes.read_text(encoding="utf-8"),
72+
json.loads(args.qualification.read_text(encoding="utf-8")),
73+
version=args.version,
74+
source_sha=args.source_sha,
75+
)
76+
# Never overwrite the source copy, qualification, or an earlier reviewed file.
77+
with args.output.open("x", encoding="utf-8", newline="\n") as output:
78+
output.write(notes)
79+
except (OSError, ValueError) as error:
80+
parser.exit(1, f"Cannot prepare release notes: {error}\n")
81+
print(f"Prepared {args.output}. Review before publishing. Nothing was published.")
82+
83+
84+
if __name__ == "__main__":
85+
main()

0 commit comments

Comments
 (0)