[pull] main from dotnet:main#186
Merged
Merged
Conversation
* Add release notes agentic workflow and skill references Cron-driven GitHub Agentic Workflow that maintains release notes branches for .NET preview/RC/GA releases. Architecture: - dotnet-release generate changes tool produces changes.json (deterministic, from VMR source-manifest.json diffs) - Agent reads changes.json and writes curated markdown for high-value features - One PR per release milestone, maintained incrementally - Respects human edits on the branch Skill references (6 docs, ~700 lines total): - quality-bar.md: what good release notes look like - vmr-structure.md: VMR branches, tags, source-manifest.json - changes-schema.md: changes.json schema reference - component-mapping.md: components, product slugs, output files - format-template.md: markdown document structure - editorial-rules.md: tone, attribution, naming Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add release notes system design document Describes the three-layer architecture (tool → agent → workflow), the source-manifest.json mechanism, branch lifecycle, and design rationale. Links from SKILL.md for discoverability. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update release notes skill docs to match actual dotnet-release CLI Tested dotnet-release v1.1.0 generate changes against the VMR (P1→P2: 1,389 changes across 21 repos). Updated docs to reflect the actual tool output: - Remove aspirational product/package fields from changes-schema.md (tool outputs repo, not product slugs) - Add labels field (optional, via --labels flag) - Fix workflow CLI syntax (positional path, --base/--head) - Update component-mapping.md: agent does repo→file routing - Remove resolved open question about package mapping - Update example JSON and jq queries to match real output Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Scope to dotnet org repos; skip microsoft/vstest for now vstest is the only microsoft org repo in the VMR manifest and is already on the infra skip list. SAML token requirements for the microsoft org can be addressed later. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix schema docs: product field exists, add labels analysis Tested --labels flag: 776/1389 changes got labels (56% coverage). Best coverage: runtime (94%), roslyn (96%), winforms/wpf (100%). Lower coverage on infra-heavy repos as expected. Corrected the schema docs — the product field IS output by the tool (repo-level mapping), just empty for infra repos. Added product back to the schema with accurate description. Added labels field documentation and updated examples/queries. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Make milestone detection deterministic Replace heuristic branch-scanning with a deterministic algorithm using three data sources: 1. releases.json → what has shipped 2. VMR eng/Versions.props on main → current development iteration 3. VMR tags → base refs for generating diffs Decision: if Versions.props iteration > latest shipped → that's the target. Exact commands provided in workflow steps 1-2. Updated DESIGN.md (milestone detection section), vmr-structure.md (version metadata + base tag discovery), and the workflow file (deterministic steps 1 and 2 with concrete examples). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add head-ref selection logic: check for target tag before using main Once main is bumped to the next iteration, it contains preview N+1 work. The agent must check if a VMR tag exists for the target milestone: - No tag → in development, use --head main - Tag exists → finalized, use --head <tag> Updated workflow step 1e and step 2 with both code paths. Added Head ref selection section to DESIGN.md explaining why this matters. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Move general docs link to README only; add component-specific links The general 'What'\''s new in .NET' link belongs in README.md, not in every component file. Component files should link to their specific docs page when one exists (runtime, libraries, SDK, ASP.NET Core, C#, EF Core). Added the dotnet/docs overview source URL so the agent can discover component-specific links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add dotnet_commit field to schema (dotnet-release v1.2.0) v1.2.0 now maps every source-repo change to its VMR codeflow commit. The new dotnet_commit field on each change entry keys into the commits dict for the dotnet/dotnet commit. Multiple source PRs typically share the same VMR commit (codeflow batches). Updated schema docs, example JSON, and field descriptions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update schema docs for dotnet-release v2.0.0 - commit field is now VMR commit (was source repo) - dotnet_commit removed (replaced by commit) - local_repo_commit added for source repo commit - product field absent for infra repos (not empty string) - Updated example and jq queries Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Evolve to multi-milestone live system with human interaction - Multi-milestone: discover all active milestones (P4 and P5 simultaneously) - Re-validate base/head refs every nightly run (tags appear, branches create, main bumps) - Branch-per-milestone on dotnet/core (release-notes/11.0-preview4, etc.) - Human interaction: respect edits, respond to PR comments, ask when unsure - Handle transitions: main bumps, new tags, release branches, PR merges - Increased safe-output limits for multi-milestone support - Updated DESIGN.md with multi-milestone discovery, human interaction model Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Compile agentic workflow; fix toolset names - Fix invalid toolsets: contents→repos, code_search→search - Add compiled release-notes.lock.yml - Add .github/aw/actions-lock.json (gh aw artifact) - Add linguist-generated gitattributes for lock files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove stale gist link from changes schema docs The inline example in this file is the authoritative reference. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add curated examples reference doc Six examples from .NET 9/10 preview release notes demonstrating three styles: - Short: exception handler diagnostics, container insecure registries - Medium: extension operators (C#), PipeReader JSON support - Long: post-quantum cryptography, OpenIdConnect PAR Added to reference docs list in workflow and DESIGN.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add JIT/runtime examples to release notes reference Three styles of JIT feature descriptions: - Array Enumeration De-Abstraction (progressive benchmarks, optimization narrative) - Struct Arguments codegen (before/after assembly comparison) - Loop Optimizations (metric-heavy prose, no code) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add ask-for-help guidance: benchmarks, samples, domain context The agent should recognize when a feature description needs content it can't generate (benchmark data, definitive code samples, domain expertise) and post PR comments requesting it from feature authors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Split examples by component for token efficiency Replace monolithic examples.md with per-component files: - examples/README.md — principles index, component directory - examples/runtime.md — 3 JIT examples with inlined content - examples/aspnetcore.md — 3 examples (short/medium/long) - examples/csharp.md — extension operators - examples/sdk.md — container insecure registries - examples/libraries.md — post-quantum cryptography Each file includes the actual example text and links back to the original source file. Agent loads only the relevant component file when writing, saving context tokens. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Reformat examples: content first, metadata in footer blocks New format per file: ## Heading (H2) Actual content (copy/paste from original) --- Source: link to original Commentary: why it was selected Why it works: what makes it effective --- Clear separation between the example content and the editorial commentary. Content reads exactly as it would in release notes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update for dotnet-release v2.1.0; fix example formatting - id field is now string (repo@commit format) — globally unique - Updated schema docs and example JSON - Removed trailing blank lines in example metadata blocks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Run every 6 hours instead of daily More frequent runs mean faster feedback loops on PR comments and quicker pickup of new VMR content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix commentary: callback example would benefit from code sample Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Replace short ASP.NET example: StatusCodeSelector with code snippet Replaces SuppressDiagnosticsCallback (prose-only) with StatusCodeSelector (one paragraph + clean code sample). Better exemplar for 'short + code'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add active voice principle to examples guide Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add style note: simplify awkward phrasing in PipeReader example Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Mark PAR example as anti-pattern; add Title/Content/Credit principle The 'guest introduction' style restructures the note around attribution instead of the feature. Prefer: explain the feature, then credit at end. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add style note: simplify transition to rule bullets in C# example Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add style note: active voice for MLDsa ease-of-use intro Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add principle: link PRs/issues in org/repo #number format Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add principle: avoid jargon and ambiguous words 'Snippet' in a programming context suggests code. Say what you mean plainly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add style note: don't bury the lede with backward-looking passive Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix markdownlint: setext headings, list numbering, table spacing Add blank lines before closing --- to prevent setext heading parsing. Fix numbered list sequence in README. Fix table separator spacing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix broken relative links; exclude lock files from super-linter Source links needed 5 levels up (not 4) from examples/ to repo root. Workflow link to examples/ fixed to use correct relative path. Exclude *.lock.yml from super-linter (generated by gh aw compile). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix remaining CI: blank line before list, README link paths Add blank line before list in workflow (MD032). Fix README.md table links — files are siblings, not in examples/ subdirectory. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove stale monolithic examples.md (replaced by examples/ directory) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add API verification guidance using dotnet-inspect - New reference doc: api-verification.md — why, when, and how to verify API names before writing about them in release notes - Updated SKILL.md: verification is now step 3 in the pipeline - Updated DESIGN.md: agent verifies before writing, not as an afterthought - Updated quality-bar.md: 'verify before you write' as a hard rule — placeholder over fabrication Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add nightly SDK download workflow for API verification - Query dotnet11 NuGet feed to find the last preview.N build - Download SDK tarball from ci.dot.net with matching version - Set DOTNET_ROOT to point dotnet-inspect at the correct build - Document why stale builds give false negatives - Add PR test fallback when nightly is unavailable - Tested: confirmed AnyNewLine=2048 in P3, ProcessStartOptions correctly absent Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Simplify API verification: query NuGet feed directly, no SDK install Replace DOTNET_ROOT/tarball approach with direct --package --source queries against the dotnet11 nightly NuGet feed. Pure data, no SDK installation needed. Link to richlander/dotnet-release#42 for dotnet-release to provide build metadata automatically. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update api-verification: use dotnet-release build-metadata pipeline Replace manual feed query with dotnet-release generate build-metadata command (v2.3.0). Show real output including all ref packs. Remove --library workaround (fixed in dotnet-inspect). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Editorial rules: prefer short sentences, avoid interrupting clauses Long sentences are fine when they flow as one thought (what → why). They're not fine when a subordinate clause interrupts the main verb. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Editorial rules: three-tier feature ordering Broad interest → cluster by area → alphabetical within cluster. Replaces vague 'customer impact' guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Editorial rules: 20/80 rule, two-sentence test, value headlines Features must matter to ≥20% of readers. Write so the other 80% understand why. If you can only write two sentences, it's probably an engineering fix — cut it. Headlines should convey value. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * SKILL.md: add examples/ to reference documents Agents weren't told to read the curated examples before writing. The examples directory has 5 component files and 12 editorial principles — our best guidance on style. Now explicitly referenced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Editorial rules: don't overstate maturity in previews Say what concretely changed (enabled by default, no opt-in needed) rather than editorializing readiness (ready for production use). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Editorial rules: filtered features comment block When cutting features for 20/80 or two-sentence test, record them in an HTML comment in the output file. Creates a learning record for future runs and human reviewers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Editorial rules: TODO for borderline entries, vet community lists - Borderline features should get a TODO comment asking for data rather than being silently included or silently cut. - Community contributor lists must be vetted: exclude -msft suffixes and other Microsoft employee indicators. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Format template: add release info and VMR refs to README README.md should include a version table and VMR base/head refs with links. Values come from build-metadata.json. Useful for tracking what was diffed and for incremental updates. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Editorial rules: dedup nuance — state changes are new news A feature introduced in P1 and enabled by default in P3 is new news. Don't skip it just because the feature name appeared in a prior preview. Document the change in state, not the feature from scratch. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Initialize Agentic Workflows agent * Set up the select-copilot-pat integration into agentic workflows * Integrate select-copilot-pat into release-notes workflow * Move labeler workflow readme to avoid it being recognized as a workflow * Apply review feedback. Set schedule to be daily around 9am PDT. * Do not run the release-notes workflow on forks unless manually dispatched * Set release-notes workflow timeout to 2 hours * Split release notes skill pipeline Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Refine release notes scoring guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Clarify release-notes editorial guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Prefer stronger verbs in release-note headings Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Refine release-notes workflow guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove redundant release-notes docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update .github/workflows/release-notes.md Co-authored-by: Jeff Handley <jeffhandley@users.noreply.github.com> * Update .github/workflows/release-notes.md Co-authored-by: Jeff Handley <jeffhandley@users.noreply.github.com> * Deduplicate editorial rubric guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Clarify preview and GA api-diff labels Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Rename maintainer release tool to release-notes-gen Update the workflow docs, repo skills, and locked workflow permissions to use the renamed maintainer CLI and package name while keeping dotnet-release for the public graph-query tool. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Jeff Handley <jeffhandley@users.noreply.github.com>
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
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
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.
See Commits and Changes for more details.
Created by
pull[bot] (v2.0.0-alpha.4)
Can you help keep this open source service alive? 💖 Please sponsor : )