factorio-changelog

name	factorio-changelog
description	Generates changelog entries for Factorio MODs from commits since the last release. Use when the user wants to update changelog.txt, add changelog entries, or document changes for a Factorio MOD.
allowed-tools	["Bash","Read","Grep"]

Factorio MOD Changelog Generation Skill

Analyzes commits since the last release and adds user-facing changes to changelog.txt using factorix mod changelog add.

Instructions

IMPORTANT: When using this skill, announce to the user: "Using factorio-changelog skill to generate changelog entries."

1. Get Last Release Tag

LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

if [ -z "$LAST_TAG" ]; then
  echo "No previous release tag found. Will analyze all commits."
fi

2. Get Commits Since Last Release

# If tag exists
git log --format="%H %s" "$LAST_TAG"..HEAD

# If no tag, get recent commits
git log --format="%H %s" -50

3. Analyze Each Commit

For each commit, determine if it has user-facing impact:

Include (user-facing):

• New features (:sparkles:)
• Bug fixes (:bug:)
• Performance improvements (:zap:)
• Breaking changes (:boom:)
• Scripting API changes (:scroll:)

Exclude (internal):

• Refactoring (:recycle:) - unless it changes behavior
• Tests (:white_check_mark:)
• CI/CD changes (:construction_worker:)
• Documentation (:memo:) - unless user-facing docs
• Code style (:art:)
• Merge commits
• Version/release prep commits (:bookmark:)

4. Categorize Changes

Map each commit to a Factorio changelog category:

Commit type	Category
New major features	Features
Minor additions	Minor Features
Bug fixes	Bugfixes
Performance improvements	Optimizations
Breaking changes / behavior changes	Changes
Scripting/API changes	Scripting

5. Determine Target Version

BRANCH=$(git branch --show-current)

if [[ "$BRANCH" =~ ^release-v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
  TARGET_VERSION="${BASH_REMATCH[1]}"
else
  TARGET_VERSION="Unreleased"
fi

6. Check Existing Entries

Before adding entries, check what's already in changelog.txt to avoid duplicates:

factorix mod changelog extract --version "$TARGET_VERSION" 2>/dev/null || echo "(no existing entries)"

7. Add Entries via factorix

For each user-facing change, run:

factorix mod changelog add "Entry text" --category="CATEGORY" --version="$TARGET_VERSION"

Entry text should:

• Start with an imperative verb (Add, Fix, Change, Remove)
• Be concise (one line)
• Focus on user impact, not implementation details

Do not include issue references — Factorio's changelog.txt is plain text displayed in-game and does not support markdown links.

Workflow

1. Get last release tag
2. List commits since that tag
3. For each commit:
   • Read commit message
   • Determine if user-facing
   • Map to Factorio category
4. Determine target version (release branch → X.Y.Z, otherwise → Unreleased)
5. Check existing entries to avoid duplicates
6. For each new entry, run factorix mod changelog add

Guidelines

Entry Writing

• Use imperative mood: "Add" not "Added" or "Adds"
• Be specific but concise
• One logical change per entry
• No issue references or markdown links

Avoiding Duplicates

• Extract current entries for target version before adding
• Skip entries that already exist

Arguments

This skill takes no arguments. It always analyzes commits from the last release tag to HEAD.