# Commandlineutils

> Prepare release notes for CommandLineUtils NuGet packages Use when this capability is needed.

- Skill: `tomevault-io/commandlineutils` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/commandlineutils`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/commandlineutils/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/commandlineutils

---


# Prepare Release

Analyzes git history, categorizes changes, and generates dual-format release notes for `releasenotes.props` (NuGet) and `CHANGELOG.md` (GitHub).

## Workflow

When preparing a release (invoked via `/prepare-release [version]` or automatically when context indicates release preparation):

### 1. Determine Version and Scope

- Parse the version number (ask if not provided)
- Identify type: **Major** (X.0.0), **Minor** (X.Y.0), or **Patch** (X.Y.Z)
- Find previous version tag for comparison

### 2. Gather Changes

Run git commands to analyze commits since last release:
- `git log` for commit history
- `git log --grep` for PR merges
- Look for conventional commit patterns: `fix:`, `feat:`, `break:`, `docs:`, etc.

### 3. Filter and Categorize Changes

**Exclude from release notes:**
- Dependabot / automated dependency bump commits (e.g., `chore(deps): Bump ...`). These are routine maintenance and not user-facing.
- CI/tooling-only changes (e.g., updating GitHub Actions workflows, claude workflows) unless they affect the shipped package.

Group remaining changes into categories (in this order):

1. **Breaking changes** (major versions only) - API removals, behavior changes
2. **Features** - New functionality or APIs
3. **Fixes** - Bug fixes and corrections
4. **Improvements** - Performance or usability enhancements
5. **Docs** - Documentation-only changes
6. **Other** - Infrastructure, tooling, CI/CD (only if user-facing or noteworthy)

### 4. Generate releasenotes.props Entry

**Format:** `* @contributor: description (#PR)`

**XML escaping:** `<` → `&lt;`, `>` → `&gt;`, `&` → `&amp;`

**Minor/Major versions:**
```xml
<PackageReleaseNotes Condition="$(VersionPrefix.StartsWith('X.Y.'))">
Changes since X.Y-1:

Breaking changes:
* @user: description (#123)

Features:
* @user: description (#124)

Fixes:
* @user: description (#125)
</PackageReleaseNotes>
```

**Patch versions:**

Append the patch notes directly at the end of the existing parent version's `StartsWith('X.Y.')` block. Do NOT create a separate conditional block. Add the patch section just before the closing `</PackageReleaseNotes>` tag of the parent version:

```xml
<PackageReleaseNotes Condition="$(VersionPrefix.StartsWith('X.Y.'))">
...existing X.Y.0 release notes...

Updates in X.Y.Z patch:
* @user: fix description (#123)
</PackageReleaseNotes>
```

For multiple patches, append each one in order at the end of the same block:

```xml
...existing X.Y.0 release notes...

Updates in X.Y.1 patch:
* @user: fix description (#123)

Updates in X.Y.2 patch:
* @user: another fix (#456)
</PackageReleaseNotes>
```

### 5. Generate CHANGELOG.md Entry

**Format:** `* [@contributor]: description ([#PR])`

**For pre-releases (beta, rc):**
- Add changes under existing "Unreleased changes" section (do NOT create new version header)
- Update the comparison link to point from last stable tag to main branch HEAD
- Rationale: Build number suffix (e.g., `-beta.{BUILD_NUMBER}`) is unknown until CI runs

```markdown
## [Unreleased changes](https://github.com/natemcmaster/CommandLineUtils/compare/vX.Y.Z...main)

### Breaking changes
* [@user]: description ([#123])

### Features
* [@user]: description ([#124])

### Fixes
* [@user]: description ([#125])

[#123]: https://github.com/natemcmaster/CommandLineUtils/pull/123
[#124]: https://github.com/natemcmaster/CommandLineUtils/pull/124
[#125]: https://github.com/natemcmaster/CommandLineUtils/pull/125
```

**For stable releases:**
- Create new version header with exact tag comparison
- Insert AFTER "Unreleased changes" section

```markdown
## [vX.Y.Z](https://github.com/natemcmaster/CommandLineUtils/compare/vX.Y.Z-1...vX.Y.Z)

### Features
* [@user]: description ([#123])

[#123]: https://github.com/natemcmaster/CommandLineUtils/pull/123
```

### 6. Update Directory.Build.props

Update `<VersionPrefix>` to match release version.

### 7. Present for Review

Show the user:
- Summary of changes by category
- Proposed `releasenotes.props` addition
- Proposed `CHANGELOG.md` addition
- `Directory.Build.props` version update

Ask for confirmation before applying changes.

### 8. Apply Changes

Once approved, edit the three files.

### 9. Final Checklist

Remind user to:
- Review generated notes for accuracy
- Run `./build.ps1` to verify build
- Create git tag: `git tag vX.Y.Z`
- Push tag: `git push origin vX.Y.Z`

## Style Guide

### Contributor Attribution

Always credit contributors:
```
* @username: description (#123)
```

For multiple contributors:
```
* @user1 and @user2: description (#123 and #456)
```

### Description Format

**Good examples:**
- `fix: find dotnet.exe correctly when DOTNET_ROOT is not set`
- `feature: add API for setting default value on options and arguments`
- `don't mask OperationCanceledException triggered by SIGINT`

**Avoid:**
- Implementation details: ~~"Refactored ValidationAttribute processing"~~
- Vague: ~~"Fixed bug"~~, ~~"Updated code"~~
- Missing attribution: ~~"Fixed parser (#123)"~~

### Optional Prefixes

Use when it adds clarity (optional under category headings):
- `fix:` - Bug fixes
- `feature:` - New features
- `cleanup:` - Code cleanup
- `docs:` - Documentation
- `bugfix:` - Alternative to "fix:"

### PR References

```
(#123)                    # single PR
(#389 and #420)          # multiple PRs
```

Omit if direct commit (no PR).

## Version-Specific Patterns

### Major Versions (X.0.0)

Lead with breaking changes prominently. Consider linking to upgrade guide.

```
Changes since X-1.Y.Z:

Breaking changes:
* @user: remove deprecated API (#251)
* @user: dropped .NET Standard 1.6 support (#337)

Features:
* [new features]

See https://natemcmaster.github.io/CommandLineUtils/vX.0/upgrade-guide.html
```

### Patch Versions

Append patch notes directly into the existing parent version's `StartsWith('X.Y.')` block in `releasenotes.props`. Do NOT create a separate conditional block or use `$(PackageReleaseNotes)` inheritance. Each patch gets an "Updates in X.Y.Z patch:" section appended at the end of the parent block.

## Quality Checklist

- [ ] All changes have contributor attribution (@username)
- [ ] All changes have PR references when applicable (#123)
- [ ] XML special characters escaped (&lt; &gt; &amp;)
- [ ] Categories in correct order
- [ ] Version condition is exact
- [ ] Footer link included and correct (version without dots)
- [ ] CHANGELOG.md has markdown link references
- [ ] Descriptions are clear and user-focused

## Examples

See `src/CommandLineUtils/releasenotes.props`:
- Version 4.0.0 - Major with breaking changes
- Version 4.0.1 - First patch
- Version 4.0.2 - Second patch
- Version 3.1.0 - Minor with features

---
> Source: [natemcmaster/CommandLineUtils](https://github.com/natemcmaster/CommandLineUtils) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->