apt-ostree/docs/CHANGELOG_WORKFLOW.md

Changelog Workflow Documentation

Overview

This document explains the different ways to work with the CHANGELOG.md file and how to safely commit changes with changelog content.

The Problem

The original post-commit git hook had several issues:

1. Infinite Loop Risk: It called git commit --amend which triggered the hook again
2. Double Amending: It tried to amend commits multiple times
3. System Instability: Could cause resource exhaustion requiring system reboot

Solutions

Option 1: Fixed Post-Commit Hook (Safest)

The post-commit hook has been fixed to:

• Temporarily disable itself during operations to prevent infinite loops
• Only amend the commit once
• Stage the cleared changelog without committing it

Usage: Just commit normally, the hook will automatically process the changelog.

Option 2: Pre-Commit Hook (Recommended)

A new pre-commit hook that:

• Runs before the commit happens
• Modifies the commit message to include changelog content
• Clears the changelog after the commit
• No risk of infinite loops

Usage: Just commit normally, the hook will automatically process the changelog.

Option 3: Manual Script (Most Control)

A manual script scripts/commit-with-changelog.sh that:

• Gives you full control over the process
• No git hooks involved
• Interactive commit message input
• Safe and predictable

Usage:

# Stage your changes first
git add .

# Run the script
./scripts/commit-with-changelog.sh

How to Use

1. Add Changes to CHANGELOG.md

Edit CHANGELOG.md and add your changes under the "Current Session Changes" section:

# apt-ostree Changelog

## Current Session Changes

- Fixed bug in container composition
- Added support for new treefile format
- Improved error handling in build process

2. Stage Your Changes

git add .

3. Commit

With hooks enabled (automatic):

git commit -m "Your commit message"

With manual script (manual control):

./scripts/commit-with-changelog.sh

Troubleshooting

If the hook causes issues:

1. Disable hooks temporarily:

   mv .git/hooks/post-commit .git/hooks/post-commit.disabled
   mv .git/hooks/pre-commit .git/hooks/pre-commit.disabled
   

2. Use the manual script instead:

   ./scripts/commit-with-changelog.sh
   

3. Reset if needed:

   git reset --soft HEAD~1  # Undo last commit
   

If you get infinite loops:

1. Kill git processes:

   pkill -f git
   

2. Disable all hooks:

   chmod -x .git/hooks/*
   

3. Reboot if system becomes unresponsive

Best Practices

1. Keep changelog entries concise - one line per change
2. Use present tense - "Fix bug" not "Fixed bug"
3. Test hooks in a safe environment before using in production
4. Have a backup plan - the manual script is always available
5. Monitor system resources when using automated hooks

Current Status

• ✅ Post-commit hook fixed (safer)
• ✅ Pre-commit hook added (recommended)
• ✅ Manual script available (most control)
• ✅ Documentation created
• ✅ All scripts are executable

Choose the approach that best fits your workflow and comfort level with automation.