Writing Modpack Changelog

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

When NOT to Use

Rules

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

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

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.

Source: hashgraph-online/awesome-codex-plugins → plugins/BB-84C/bgs-modding-superpowers/skills/writing-modpack-changelog/SKILL.md