Quick Reference

This page consolidates essential information needed when generating release notes. It is organized for quick lookup of command usage, workflow summary, output file paths, and troubleshooting. Refer to the corresponding section’s main text for full context.

Command Usage

The basic format is as follows.

/release-note <version>

The version parameter follows the SemVer format and supports pre-release tags.

Command	Description
/release-note v1.0.0	First deployment
/release-note v1.2.0	Regular release
/release-note v1.2.0-alpha.1	Alpha release
/release-note v1.2.0-beta.1	Beta release
/release-note v1.2.0-rc.1	Release candidate

5-Phase Workflow Summary

A single command executes five Phases sequentially. Here is a summary of each Phase’s goal, execution content, and output.

Phase	Goal	Key Command/Action	Output
1	Environment validation	git status, dotnet --version	Base/Target determination
2	Data collection	dotnet AnalyzeAllComponents.cs	.analysis-output/*.md
3	Commit analysis	Breaking Changes, Feature classification	work/phase3-*.md
4	Document writing	TEMPLATE.md → RELEASE-*.md	RELEASE-{VERSION}.md
5	Validation	API accuracy, “Why this matters” section check	work/phase5-*.md

Phase 1: Environment Validation

# Required checks
git status              # Verify Git repository
dotnet --version        # .NET 10.x or higher required
ls .release-notes/scripts  # Verify scripts directory

Base Branch Determination:

• If origin/release/1.0 exists → Use as Base
• If not (first deployment) → git rev-list --max-parents=0 HEAD

Phase 2: Data Collection

cd .release-notes/scripts

# Component analysis
dotnet AnalyzeAllComponents.cs --base <base-branch> --target HEAD

# API change extraction
dotnet ExtractApiChanges.cs

Phase 3: Commit Analysis

There are two methods for detecting Breaking Changes, with Git Diff analysis taking priority.

1. Git Diff analysis (recommended): Deleted/changed APIs in api-changes-diff.txt
2. Commit message patterns: type!:, BREAKING CHANGE keywords

Phase 4: Document Writing

# Copy template
cp .release-notes/TEMPLATE.md .release-notes/RELEASE-v1.2.0.md

# Replace placeholders
# {VERSION} → v1.2.0
# {DATE} → 2025-12-22

Phase 5: Validation

# Verify frontmatter
head -5 .release-notes/RELEASE-v1.2.0.md

# Check "Why this matters" sections
grep -c "**Why this matters:**" .release-notes/RELEASE-v1.2.0.md

# Markdown validation (optional)
npx markdownlint-cli@0.45.0 .release-notes/RELEASE-v1.2.0.md --disable MD013

Four Key Principles

Four principles that determine the quality of release notes. Understanding why each principle exists clarifies what to check during review.

1. Accuracy First

Never document an API that is not in the Uber file.

Because LLMs can “plausibly” generate API signatures. The Uber file (all-api-changes.txt) is extracted from the actually built DLL, so it must serve as the source of truth.

# Verify API existence
grep -n "MethodName" .analysis-output/api-changes-build-current/all-api-changes.txt

2. Value Delivery Required

Include a “Why this matters:” section for all major features.

A list of API changes alone makes it difficult for users to decide whether to upgrade. Each feature must explain what problem it solves and what benefits it provides for the release notes to deliver practical value.

### New Feature: TraverseSerial

A method for processing collections sequentially.

**Why this matters:**
- Suitable for tasks requiring order guarantees
- Memory-efficient processing

3. Automatic Breaking Change Detection

Git Diff analysis takes priority over commit message patterns.

Developers may forget to mark BREAKING CHANGE in commit messages. In contrast, Git diffs of the .api folder objectively show actual API changes, enabling detection of Breaking Changes without omissions.

• Git diff analysis of the .api folder (objective)
• Commit message patterns are supplementary

4. Traceability

Trace all features to actual commits.

Features described in the release notes must be traceable to the commits where they were implemented. This serves as a starting point for later examining implementation details or investigating issues.

<!-- Related commit: abc1234 -->
### New Feature: ErrorCodeFactory

Key Output Files

Files generated by the workflow, organized by purpose.

Final Deliverable

File	Description
.release-notes/RELEASE-{VERSION}.md	Release notes

Analysis Results

File	Description
.analysis-output/Functorium.md	Core library analysis
.analysis-output/Functorium.Testing.md	Test library analysis
.analysis-output/analysis-summary.md	Overall summary

API-Related

File	Description
api-changes-build-current/all-api-changes.txt	Uber file (all Public APIs)
api-changes-build-current/api-changes-diff.txt	API changes (Git diff)

Intermediate Artifacts

Work files generated by each Phase. Useful for checking how far processing succeeded when problems occur.

File	Description
work/phase3-commit-analysis.md	Commit classification results
work/phase3-feature-groups.md	Feature grouping
work/phase4-draft.md	Release notes draft
work/phase5-validation-report.md	Validation results

Troubleshooting

Common problems and solutions in table form. See the Troubleshooting Guide for detailed explanations.

Problem	Solution
Base Branch not found	Auto-detected as first deployment, analyzes from initial commit
.NET SDK version error	.NET 10.x installation required
File lock issue	taskkill /F /IM dotnet.exe (Windows)
API validation failure	Verify correct API name in Uber file

Use the following commands when a full environment reset is needed.

Full Reset (Windows)

Stop-Process -Name "dotnet" -Force -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .release-notes\scripts\.analysis-output -ErrorAction SilentlyContinue
dotnet nuget locals all --clear

Full Reset (macOS/Linux)

pkill -f dotnet
rm -rf .release-notes/scripts/.analysis-output
dotnet nuget locals all --clear

Checklist

Items to check before and after release note generation.

Before Generation

• Git repository verified
• .NET 10.x SDK installed
• .release-notes/scripts/ directory exists

After Generation

• Frontmatter included
• All required sections included
• “Why this matters” section included for all major features
• All code examples verified against Uber file
• Breaking Changes documented (if any)
• Migration guide included (if Breaking Changes exist)

Reference Documentation

Document	Description
release-note.md	Release note Command definition
TEMPLATE.md	Release note template
phase1-setup.md	Phase 1 details
phase2-collection.md	Phase 2 details
phase3-analysis.md	Phase 3 details
phase4-writing.md	Phase 4 details
phase5-validation.md	Phase 5 details

FAQ

Q1: Under the “Accuracy First” principle, if APIs not in the Uber file are not documented, how are new features that haven’t been built yet handled?

A: Release notes only document features whose implementation is complete. Since Phase 2 builds with dotnet publish and then extracts APIs from the DLL, features whose code doesn’t compile are not included in the Uber file. Features still under development must be documented in the next release.

Q2: What specifically does the checklist item “All code examples verified against Uber file” check?

A: It verifies that class names, method names, and parameter types appearing in the release notes’ code examples exactly match the API signatures in the Uber file. For example, if a code example uses ErrorCodeFactory.Create(), the Uber file must contain that method with an identical signature.

Q3: Is it safe to forcefully terminate dotnet processes in the full reset commands?

A: Ideally, only dotnet processes related to release note script execution should be terminated, but if no other dotnet applications are running simultaneously, taskkill /F /IM dotnet.exe (Windows) or pkill -f dotnet (macOS/Linux) for full termination is not a problem. If other .NET services are running, check the PID of those processes and terminate selectively.

Q4: Does this quick reference guide need to be updated with each new version?

A: It only needs updating when the workflow structure or commands change. The /release-note command usage, 5-Phase structure, output file paths, etc. are system structure information independent of version, so they can be used as-is unless the release note automation system itself is improved.

This concludes the hands-on part of the release note automation. The following appendix provides a glossary and additional reference materials.

• Appendix A: Glossary