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 guidelines and examples.

Architectural Decision Records (ADR)

To create architectural decision records:

1. Use scripts/create_adr.py to scaffold new ADR file
2. Number ADRs sequentially (0001-title.md, 0002-title.md)
3. Include standard sections: Context, Decision, Consequences
4. Document alternatives considered
5. Reference related ADRs

Use assets/adr-template.md as starting point for new ADRs.

ADR Structure

Standard ADR sections:

• Title: Short, descriptive name
• Status: Proposed, Accepted, Deprecated, Superseded
• Context: What problem are we solving?
• Decision: What did we decide to do?
• Consequences: What are the tradeoffs and impacts?
• Alternatives Considered: What other options were evaluated?

Product Requirement Documents (PRD)

To scaffold product requirement documents:

1. Use scripts/create_prd.py to generate PRD template
2. Define problem statement and goals
3. List functional and non-functional requirements
4. Include user stories and acceptance criteria
5. Document technical constraints and dependencies

Reference assets/prd-template.md for comprehensive PRD structure.

PRD Sections

Standard PRD components:

• Overview: High-level description
• Problem Statement: What problem are we solving?
• Goals and Non-Goals: Scope definition
• User Stories: Who, what, why format
• Requirements: Functional and non-functional
• Design Considerations: UI/UX, architecture
• Success Metrics: How to measure success
• Timeline: Development phases

Implementation Steps

Generate Changelog from Commits

To generate changelog:

1. Collect Commits

   python scripts/generate_changelog.py --since v1.0.0
   

2. Categorize Changes

   • Parse commit messages for conventional commit types
   • Extract breaking changes
   • Group by scope if present

3. Format Output

   • Generate markdown with appropriate headings
   • Link to commits and PRs
   • Add version header with date

4. Update CHANGELOG.md

   • Prepend new version section
   • Maintain existing content
   • Update “Unreleased” section

Create New ADR

To document architectural decision:

1. Generate ADR File

   python scripts/create_adr.py "use postgresql for entity storage"
   

2. Fill Template

   • Document context and constraints
   • Explain decision rationale
   • List consequences and tradeoffs

3. Review and Commit

   • Get team feedback
   • Update status to “Accepted”
   • Link from main architecture docs

Scaffold New PRD

To create product requirements:

1. Generate PRD Template

   python scripts/create_prd.py "timeline visualization feature"
   

2. Complete Sections

   • Define problem and goals
   • Write user stories
   • List requirements

3. Review with Stakeholders

   • Get product team input
   • Validate technical feasibility
   • Refine scope and requirements

Automation

To automate documentation updates:

Release Workflow Integration

Add to .github/workflows/release.yml:

- name: Generate changelog
  run: python scripts/generate_changelog.py --output CHANGELOG.md

- name: Commit changelog
  run: |
    git config user.name github-actions
    git config user.email github-actions@github.com
    git add CHANGELOG.md
    git commit -m "docs: update changelog for ${{ github.ref_name }}"

Pre-commit Hook

Add to .git/hooks/commit-msg:

#!/bin/bash
# Validate conventional commit format
python scripts/validate_commit_msg.py "$1"

Documentation Structure

Organize project documentation:

docs/
├── CHANGELOG.md           # Version history
├── ADR/                   # Architectural decisions
│   ├── 0001-use-nextjs.md
│   └── 0002-database-choice.md
├── PRD/                   # Product requirements
│   ├── timeline-feature.md
│   └── entity-relationships.md
└── api/                   # API documentation
    └── endpoints.md

Best Practices

Changelog

• Write for users, not developers
• Use present tense (“Add” not “Added”)
• Link to relevant issues/PRs
• Highlight breaking changes prominently
• Keep entries concise and clear

ADR

• Write when decision is made, not after
• Document alternatives considered
• Be honest about tradeoffs
• Update status if decision changes
• Link related ADRs

PRD

• Start with user needs, not solutions
• Include success metrics
• Define scope clearly (goals and non-goals)
• Get stakeholder buy-in early
• Update as requirements evolve

Version Management

To manage semantic versioning:

1. MAJOR: Breaking changes (incompatible API changes)
2. MINOR: New features (backward-compatible)
3. PATCH: Bug fixes (backward-compatible)

Use scripts/bump_version.py to update version across package.json, changelog, and tags.

Release Notes

To generate release notes:

1. Extract relevant changelog section
2. Add highlights and notable changes
3. Include upgrade instructions if needed
4. Link to full changelog
5. Publish to GitHub releases

Use scripts/generate_release_notes.py to create formatted release notes from changelog.

Troubleshooting

Common issues:

• Commits Not Categorized: Ensure commits follow Conventional Commits format
• Missing Version: Tag releases in git with semantic version numbers
• Duplicate Entries: Check for merge conflicts in CHANGELOG.md
• Broken Links: Verify commit SHAs and PR numbers are correct