writing-modpack-changelog

name	writing-modpack-changelog
description	Use when cutting a modpack release. Creates <project>/docs/release-changelog.md if absent; appends a new version section with grouped changes. Triggers - 'cut a release', 'release notes', 'changelog', 'v1.2.3 changes', 'what changed since last version'.

Overview

The modpack release changelog is the user-visible record of what changed between releases, grouped by semantic category: Added, Changed, Fixed, Removed, and Compatibility. This skill replaces the deleted templates/modpack/release-changelog.md template by creating <project>/docs/release-changelog.md at runtime, then inserting a new version section whenever the curator cuts a release.

When to Use

Use this skill when...	Result
The user says "cut a release", "release notes", "changelog", or "what changed since last version"	Create or update the release changelog.
A target version is being prepared for Nexus, ModDB, a Discord post, a GitHub release, or another player-facing surface	Produce grouped, readable release notes.
The user wants changes since the last tag, version, or release section	Summarize those changes into semantic buckets.
The user has finished a modpack milestone	Insert a new version section newest-first.
The user asks whether the release is major, minor, or patch	Suggest a version bump based on modpack impact.

When NOT to Use

Do not use this skill when...	Use instead
The user made a random working change and wants to remember it later	writing-modpack-devlog
The user wants a single-mod curator note	writing-modpack-devlog
The user asks for plugin inspection or conflict resolution	xedit-automation or xedit-conflict-audit first.
There is no release boundary, version, tag, or player-facing summary intent	Keep working; do not invent a release.
The user needs to set up the modpack project structure first	setting-up-bgs-modding-environment

Rules

This skill writes release notes for humans. It does not install mods, alter game files, change load order, publish to Nexus, or open a release page. Draft the changelog locally; any public posting or release publication requires explicit user confirmation outside this skill.

1. Detect the modpack project root before writing.
   • If the user provides <modpack_project_root>, use it.
   • If the current working directory looks like a modpack directory because it already has Data/, profiles/, or docs/, default to pwd and tell the user what default you used.
   • Otherwise ask once: "Which modpack project root should I use? I can default to the current directory if this is the project root."
2. Locate <project>/docs/release-changelog.md.
   • If <project>/docs/ does not exist, create it.
   • If release-changelog.md is missing, create it before inserting the version.
3. On first creation, use this header shape:
   • # <Project Name> Release Changelog
   • One-line intro: Player-facing release notes for <Project Name>. Newest releases are listed first.
   • ## Releases
4. Determine the target version.
   • If the user provides a version, use it exactly after checking that it is not already present.
   • If the user does not provide a version, read the newest release heading and ask for the new version once.
   • Suggest a semver bump: major for load-order-breaking or save-breaking changes, minor for added mods or compatibility tweaks, patch for fixes only.
5. Use the current local date for the release date unless the user provides a specific release date.
   • Version headings use ## <version> (<release-date>).
   • Use YYYY-MM-DD for release dates.
6. Each version section must use semantic buckets:
   • ### Added
   • ### Changed
   • ### Fixed
   • ### Removed
   • ### Compatibility
7. Omit empty buckets.
   • Do not leave placeholder headings such as ### Removed with "None" under them unless the user explicitly wants a full template.
8. Insert versions newest-first under ## Releases.
   • Insert the new version immediately below ## Releases.
   • If the file already uses oldest-first and the user wants to preserve it, follow the existing convention and note that choice.
9. Optionally consume the dev-log.
   • If <project>/docs/dev-log.md exists, offer to summarize entries since the last release into the appropriate buckets.
   • The user must confirm or edit the proposed summary before you write it into the changelog.
   • Do not blindly convert every dev-log entry into player-facing copy; curator noise stays in the dev-log.
10. Write for players, not for internal tooling.
    • Keep entries concrete and readable.
    • Avoid private debugging details, raw conflict jargon, and internal agent process notes.
    • Mention mod names when they help users understand compatibility or upgrade risk.
11. Do not duplicate an existing version.
    • If the target version heading already exists, ask whether to amend that section or choose a new version.
    • Do not insert a second ## <version> heading.
12. After writing, report the file path, version, release date, buckets included, and whether dev-log entries were consumed.

Quick Reference

Field	Canonical shape	Example
File	<project>/docs/release-changelog.md	docs/release-changelog.md
Version heading	## <version> (<release-date>)	## v1.4.0 (2026-06-01)
Bucket heading	### Added, ### Changed, ### Fixed, ### Removed, ### Compatibility	### Compatibility
Entry style	Short player-facing bullet	- Added a patch for Example Weather and Example Lighting.
Ordering	Newest release first under ## Releases	v1.4.0 above v1.3.2

Canonical version shape:

## v1.4.0 (2026-06-01)

### Added

- Added Example Weather Overhaul and its modpack patch.

### Changed

- Rebalanced the early-game survival settings for slower hunger and thirst gain.

### Fixed

- Fixed missing workshop keywords in the settlement compatibility patch.

### Compatibility

- Added compatibility notes for Example Lighting Overhaul users upgrading from v1.3.x.

Examples

Bad

Changed a bunch of stuff:
- new weather
- fixed bugs
- removed old patch

This has no version, no release date, no grouping, and no signal about compatibility risk.

Good

## v1.4.0 (2026-06-01)

### Added

- Added Example Weather Overhaul with a curated modpack patch.

### Changed

- Updated settlement lighting balance in the downtown cells.

### Fixed

- Fixed missing workshop keywords caused by the lighting compatibility patch.

### Removed

- Removed the obsolete Example Weather Hotfix; its changes are now included upstream.

### Compatibility

- Save-compatible for existing v1.3.x users, but users with custom lighting patches should rebuild their conflict patch.

This section gives players the version, date, grouped changes, and upgrade risk in one place.

Common Mistakes

• Using the changelog for rough working notes that belong in the dev-log.
• Forgetting the version or release date.
• Dumping ungrouped bullets under one heading.
• Leaving empty bucket headings in the final changelog.
• Copying raw dev-log text without translating it for players.
• Hiding compatibility or save-risk information because it sounds negative.
• Creating duplicate version headings.
• Asking repeated version questions instead of suggesting a semver bump.
• Publishing release notes directly instead of drafting them for user review.
• Overstating changes with marketing language instead of concrete release facts.

Rationalizations

Excuse	Reality
"The dev-log already says what changed."	The dev-log is curator history. The changelog is player-facing release communication. They need different detail and tone.
"A single bullet list is faster."	Grouped buckets let users scan for added content, fixes, removals, and compatibility risk.
"Empty headings show that we considered every category."	Empty headings are noise in release notes. Omit empty buckets unless the user asked for a full template.
"I do not know the version, so I will invent one."	Ask once and suggest a bump. Version numbers are release authority, not filler text.
"The conflict details are important, so I will paste them all."	Players need the effect and upgrade risk. Keep raw conflict evidence in the dev-log or artifacts.
"This is just a patch release, so no changelog is needed."	Patch releases still need a record of what was fixed and whether users should update.
"Compatibility notes make the release look risky."	Hidden risk is worse. Clear compatibility notes reduce support burden.
"The user said release notes, so I can post them."	This skill drafts local changelog text. Public posting is a separate confirmed action.

See also

• writing-modpack-devlog - use for curator-facing chronological work records.
• setting-up-bgs-modding-environment - use when the modpack project root or docs structure must be established first.