# 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**:
```bash
# 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:

```markdown
# 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

```bash
git add .
```

### 3. Commit

**With hooks enabled** (automatic):
```bash
git commit -m "Your commit message"
```

**With manual script** (manual control):
```bash
./scripts/commit-with-changelog.sh
```

## Troubleshooting

### If the hook causes issues:

1. **Disable hooks temporarily**:
   ```bash
   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**:
   ```bash
   ./scripts/commit-with-changelog.sh
   ```

3. **Reset if needed**:
   ```bash
   git reset --soft HEAD~1  # Undo last commit
   ```

### If you get infinite loops:

1. **Kill git processes**:
   ```bash
   pkill -f git
   ```

2. **Disable all hooks**:
   ```bash
   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.