-
Notifications
You must be signed in to change notification settings - Fork 39
Forward-merge release/0.5 into main #385
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
8cfb71d
docs: reorganize plugin documentation (#361)
willkill07 1b610f2
docs: update 0.5 release notes (#362)
willkill07 dd55c28
fix: generate references for published packages (#378)
willkill07 0486d88
chore: add NAT reviewers for docs (#384)
willkill07 c4faa2e
Merge release/0.5 into main
willkill07 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| --- | ||
| name: draft-release-notes | ||
| description: Compare NeMo Relay release branches and draft or update the documentation-site release notes. Use when preparing a release-notes update under docs/about-nemo-relay/release-notes, reviewing release-to-release changes, or gathering evidence for a current release summary. | ||
| --- | ||
|
|
||
| # Draft Release Notes | ||
|
|
||
| Draft the three documentation-site release-notes pages from verified repository | ||
| evidence. Keep complete, PR-by-PR release history in GitHub Releases. | ||
|
|
||
| ## Gather Evidence | ||
|
|
||
| Run the read-only helper with explicit release refs and the target minor version: | ||
|
|
||
| ```bash | ||
| python3 .agents/skills/draft-release-notes/scripts/collect_release_evidence.py \ | ||
| --previous release/<previous-major>.<previous-minor> \ | ||
| --current HEAD \ | ||
| --version <major>.<minor> | ||
| ``` | ||
|
|
||
| The report verifies both refs, compares their release-notes trees, identifies | ||
| version text currently present in those pages, and groups commits into review | ||
| candidates. Treat the groups as an evidence index, not publication-ready copy. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Confirm the target release version from the release branch and package | ||
| metadata. Preserve unrelated working-tree changes. | ||
| 2. Run the helper. It reports an absent prior release-notes directory without | ||
| failing, which is expected for early release branches. | ||
| 3. Verify each candidate claim in the changed public docs, API types, command | ||
| help, or source before including it. Prioritize breaking changes, migrations, | ||
| user-visible features, and ongoing support limitations. | ||
| 4. Update only these pages unless the release changes their route or entry | ||
| points: | ||
| - `docs/about-nemo-relay/release-notes/index.mdx` | ||
| - `docs/about-nemo-relay/release-notes/highlights.mdx` | ||
| - `docs/about-nemo-relay/release-notes/known-issues.mdx` | ||
| 5. Keep the existing page roles: | ||
| - `index.mdx` gives the current-release summary, compatibility notes, scope, | ||
| and curated feature links. | ||
| - `highlights.mdx` groups notable changes by user-facing theme. | ||
| - `known-issues.mdx` records current limitations, compatibility migrations, | ||
| current-release fixes, and the complete fixed-item history recorded in | ||
| earlier release-note pages. Preserve every prior fixed-item bullet under | ||
| release-labelled subsections; do not summarize, deduplicate, or omit it. | ||
| GitHub Releases remains the complete PR-by-PR history. | ||
| 6. Preserve MDX front matter and the JSX SPDX comment. State the full history | ||
| is available in GitHub Releases; do not create a changelog or GitHub Release | ||
| body from this skill. | ||
|
|
||
| ## Validate | ||
|
|
||
| Run the helper for the target release and for an early branch without release | ||
| notes when available. Review public claims, then run: | ||
|
|
||
| ```bash | ||
| git diff --check | ||
| just docs | ||
| just docs-linkcheck | ||
| ``` | ||
|
|
||
| Check product names, commands, package names, support claims, and links against | ||
| the current repository before handing off the draft. |
187 changes: 187 additions & 0 deletions
187
.agents/skills/draft-release-notes/scripts/collect_release_evidence.py
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,187 @@ | ||
| #!/usr/bin/env python3 | ||
| # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
|
|
||
| """Collect read-only Git evidence for NeMo Relay documentation release notes.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import argparse | ||
| import re | ||
| import subprocess | ||
| from dataclasses import dataclass | ||
| from pathlib import Path | ||
|
|
||
| RELEASE_NOTES_DIR = "docs/about-nemo-relay/release-notes" | ||
| VERSION_PATTERN = re.compile(r"(?:NVIDIA )?NeMo Relay (\d+\.\d+(?:\.\d+)?)") | ||
|
|
||
|
|
||
| @dataclass(frozen=True) | ||
| class Commit: | ||
| """One non-merge commit and its changed paths.""" | ||
|
|
||
| sha: str | ||
| subject: str | ||
| paths: tuple[str, ...] | ||
|
|
||
|
|
||
| def run_git(repo: Path, *args: str) -> str: | ||
| """Run Git without a shell and return stdout or raise a readable error.""" | ||
| result = subprocess.run( | ||
| ["git", *args], | ||
| cwd=repo, | ||
| check=False, | ||
| capture_output=True, | ||
| encoding="utf-8", | ||
| ) | ||
| if result.returncode: | ||
| detail = result.stderr.strip() or result.stdout.strip() | ||
| raise RuntimeError(f"git {' '.join(args)} failed: {detail}") | ||
| return result.stdout | ||
|
|
||
|
|
||
| def resolve_ref(repo: Path, ref: str) -> str: | ||
| """Return the commit ID for a user-supplied ref.""" | ||
| return run_git(repo, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}").strip() | ||
|
|
||
|
|
||
| def note_files(repo: Path, ref: str) -> tuple[str, ...]: | ||
| """List release-note files that exist at a ref.""" | ||
| output = run_git(repo, "ls-tree", "-r", "--name-only", ref, "--", RELEASE_NOTES_DIR) | ||
| return tuple(path for path in output.splitlines() if path) | ||
|
|
||
|
|
||
| def note_versions(repo: Path, ref: str, paths: tuple[str, ...]) -> tuple[str, ...]: | ||
| """Return the NeMo Relay versions mentioned in release-note files.""" | ||
| versions: set[str] = set() | ||
| for path in paths: | ||
| content = run_git(repo, "show", f"{ref}:{path}") | ||
| versions.update(VERSION_PATTERN.findall(content)) | ||
| return tuple(sorted(versions)) | ||
|
|
||
|
|
||
| def commits(repo: Path, previous: str, current: str) -> tuple[Commit, ...]: | ||
| """Read non-merge commits and their changed paths, newest first.""" | ||
| output = run_git(repo, "log", "--no-merges", "--format=%H%x09%s", f"{previous}..{current}") | ||
| collected: list[Commit] = [] | ||
| for line in output.splitlines(): | ||
| sha, subject = line.split("\t", maxsplit=1) | ||
| names = run_git(repo, "diff-tree", "--no-commit-id", "--name-status", "-r", sha) | ||
| paths = tuple(entry.rsplit("\t", maxsplit=1)[-1] for entry in names.splitlines() if entry) | ||
| collected.append(Commit(sha=sha, subject=subject, paths=paths)) | ||
| return tuple(collected) | ||
|
|
||
|
|
||
| def category(commit: Commit) -> str: | ||
| """Classify a commit for review without treating the result as a release claim.""" | ||
| subject = commit.subject.lower() | ||
| if "!" in commit.subject.split(":", maxsplit=1)[0] or re.search( | ||
| r"\b(remove|drop|breaking|deprecat|migration)\b", subject | ||
| ): | ||
| return "Breaking and migration candidates" | ||
| if subject.startswith("feat"): | ||
| return "Feature candidates" | ||
| if subject.startswith(("fix", "perf")): | ||
| return "Fix candidates" | ||
| return "Documentation and tooling candidates" | ||
|
|
||
|
|
||
| def public_paths(commits_to_report: tuple[Commit, ...]) -> tuple[str, ...]: | ||
| """Return changed paths likely to support public release-note claims.""" | ||
| package_paths = { | ||
| "Cargo.toml", | ||
| "crates/node/package.json", | ||
| "integrations/openclaw/package.json", | ||
| "python/plugin/pyproject.toml", | ||
| } | ||
| return tuple( | ||
| sorted( | ||
| { | ||
| path | ||
| for commit in commits_to_report | ||
| for path in commit.paths | ||
| if path == "README.md" | ||
| or path.startswith("docs/") | ||
| or path.endswith("/README.md") | ||
| or path in package_paths | ||
| } | ||
| ) | ||
| ) | ||
|
|
||
|
|
||
| def print_note_tree(repo: Path, label: str, ref: str) -> None: | ||
| """Print structure and version mentions for one release ref.""" | ||
| paths = note_files(repo, ref) | ||
| print(f"## {label} Release-Notes Tree") | ||
| if not paths: | ||
| print(f"No files exist under `{RELEASE_NOTES_DIR}` at `{ref}`.\n") | ||
| return | ||
| print("Files:") | ||
| for path in paths: | ||
| print(f"- `{path}`") | ||
| versions = note_versions(repo, ref, paths) | ||
| description = ", ".join(versions) if versions else "no NeMo Relay version text detected" | ||
| print(f"Version text: {description}\n") | ||
|
|
||
|
|
||
| def main() -> int: | ||
| """Parse arguments and print the evidence report.""" | ||
| parser = argparse.ArgumentParser(description=__doc__) | ||
| parser.add_argument("--previous", required=True, help="Previous release branch or commit") | ||
| parser.add_argument("--current", required=True, help="Current release branch or commit") | ||
| parser.add_argument("--version", required=True, help="Target major.minor release version") | ||
| parser.add_argument("--repo", default=".", help="Repository root (default: current directory)") | ||
| args = parser.parse_args() | ||
|
|
||
| repo = Path(args.repo).resolve() | ||
| try: | ||
| previous_sha = resolve_ref(repo, args.previous) | ||
| current_sha = resolve_ref(repo, args.current) | ||
| run_git(repo, "merge-base", "--is-ancestor", previous_sha, current_sha) | ||
| except RuntimeError as error: | ||
| parser.error(str(error)) | ||
|
|
||
| print(f"# Release-Note Evidence: {args.version}") | ||
| print() | ||
| print(f"- Previous: `{args.previous}` ({previous_sha[:12]})") | ||
| print(f"- Current: `{args.current}` ({current_sha[:12]})") | ||
| print(f"- Merge base: `{run_git(repo, 'merge-base', previous_sha, current_sha).strip()[:12]}`") | ||
| print() | ||
| print_note_tree(repo, "Previous", args.previous) | ||
| print_note_tree(repo, "Current", args.current) | ||
|
|
||
| changes = commits(repo, previous_sha, current_sha) | ||
| grouped: dict[str, list[Commit]] = { | ||
| "Breaking and migration candidates": [], | ||
| "Feature candidates": [], | ||
| "Fix candidates": [], | ||
| "Documentation and tooling candidates": [], | ||
| } | ||
| for commit in changes: | ||
| grouped[category(commit)].append(commit) | ||
|
|
||
| print("## Commit Candidates") | ||
| for heading, entries in grouped.items(): | ||
| print(f"### {heading}") | ||
| if not entries: | ||
| print("- None") | ||
| for commit in entries: | ||
| paths = ", ".join(f"`{path}`" for path in commit.paths[:4]) | ||
| suffix = f" — {paths}" if paths else "" | ||
| print(f"- `{commit.sha[:12]}` {commit.subject}{suffix}") | ||
| print() | ||
|
|
||
| print("## Changed Public Documentation and Package Surfaces") | ||
| paths = public_paths(changes) | ||
| if paths: | ||
| for path in paths: | ||
| print(f"- `{path}`") | ||
| else: | ||
| print("- None") | ||
| print() | ||
| print("Review every candidate against current public docs and APIs before drafting prose.") | ||
| return 0 | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| raise SystemExit(main()) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.