# Debian Changelog Validation

The `validate-debian-changelog.sh` script implements automated validation rules for debian changelog creation based on the execution environment.

## Rules

### Local Development Environment
When running locally or in non-release branches:

1. ✅ Creates an **automated changelog entry** with build information
2. ⚠️ **Shows warning** that the autogenerated changelog should NOT be committed
3. ℹ️ Prepends warning message to changelog entries

**Example output:**
```
⚠️  WARNING: Automated debian/changelog created. DO NOT COMMIT this version!
⚠️  Please update debian/changelog manually with proper release notes before committing.
```

### CI Pipeline on Release/Main Branch
When running in CI on `release/*` or main branch:

1. 🔍 **Validates** debian/changelog version matches CHANGELOG.md version
2. ❌ **Fails build** if versions don't match
3. ✅ **Continues** if versions match

**Validation logic:**
- Extracts version from `CHANGELOG.md`: first `## [x.y.z]` pattern after `[Unreleased]`
- Extracts version from `debian/changelog`: first line format `ekfsm (x.y.z-revision)`
- Compares versions and fails if mismatch detected

## Environment Detection

```bash
# CI Detection
is_ci_environment() {
    [[ -n "$CI" ]]
}

# Release/Main Branch Detection
is_release_or_main_branch() {
    [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]] || [[ "$CI_COMMIT_BRANCH" =~ ^release/ ]]
}
```

## Usage

### Manual Execution
```bash
./scripts/validate-debian-changelog.sh
```

### Integrated in Build Process
The script is automatically called in `build-deb.sh`:

```bash
# Validate and create/check debian changelog
"$SCRIPT_DIR/validate-debian-changelog.sh"
```

## Best Practices

1. **Local Development**: Let script create automated entries, but manually update before committing
2. **Release Preparation**: Ensure debian/changelog version matches CHANGELOG.md before merging to release branch
3. **CI Integration**: Script prevents releases with mismatched versions

## Error Messages

- `❌ ERROR: Version mismatch detected!` - Versions don't match in CI
- `❌ ERROR: No debian/changelog found on release/main branch` - Missing changelog in production
- `❌ ERROR: CHANGELOG.md not found` - Missing main changelog file

## Success Messages

- `✅ Version validation passed: x.y.z` - Versions match in CI
- `✅ Validation successful - versions match` - All validations passed
