docs-and-changelogs

# Documentation and Changelogs

Generate and maintain project documentation including changelogs, architectural decision records, and product requirement documents.

## Overview

To manage project documentation effectively:

1. Generate changelogs from git commit history using Conventional Commits
2. Maintain CHANGELOG.md with semantic versioning
3. Create architectural decision records (ADR) for significant decisions
4. Scaffold product requirement documents (PRD) for new features
5. Automate documentation updates as part of release process

## Changelog Generation

To generate changelogs from Conventional Commits:

1. Parse git commit history for conventional commit messages
2. Categorize commits by type (feat, fix, chore, docs, etc.)
3. Group by version/release using git tags
4. Format according to Keep a Changelog standards
5. Append to existing CHANGELOG.md or create new file

Use `scripts/generate_changelog.py` to automate changelog generation from commit history.

### Conventional Commits Format

Follow this commit message structure:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, semicolons, etc.)
- `refactor`: Code refactoring without feature changes
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
- `ci`: CI/CD changes

**Breaking Changes:**
- Add `BREAKING CHANGE:` in footer or `!` after type
- Example: `feat!: redesign entity schema structure`

## CHANGELOG.md Maintenance

To maintain changelog file:

1. Structure with sections: Unreleased, versioned releases
2. Use semantic versioning (MAJOR.MINOR.PATCH)
3. Group changes by category (Added, Changed, Deprecated, Removed, Fixed, Security)
4. Include links to commits and pull requests
5. Add release dates in ISO format (YYYY-MM-DD)

Consult `references/changelog-format.md` for detailed formatting