Documentation and Changelogs

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

Overview

To manage project documentation effectively:

• Generate changelogs from git commit history using Conventional Commits

• Maintain CHANGELOG.md with semantic versioning

• Create architectural decision records (ADR) for significant decisions

• Scaffold product requirement documents (PRD) for new features

• Automate documentation updates as part of release process

Changelog Generation

To generate changelogs from Conventional Commits:

• Parse git commit history for conventional commit messages

• Categorize commits by type (feat, fix, chore, docs, etc.)

• Group by version/release using git tags

• Format according to Keep a Changelog standards

• 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:

• Structure with sections: Unreleased, versioned releases

• Use semantic versioning (MAJOR.MINOR.PATCH)

• Group changes by category (Added, Changed, Deprecated, Removed, Fixed, Security)

• Include links to commits and pull requests

• 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:

• Use scripts/create_adr.py to scaffold new ADR file

• Number ADRs sequentially (0001-title.md, 0002-title.md)

• Include standard sections: Context, Decision, Consequences

• Document alternatives considered

• 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:

• Use scripts/create_prd.py to generate PRD template

• Define problem statement and goals

• List functional and non-functional requirements

• Include user stories and acceptance criteria

• 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:

Collect Commits

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

Categorize Changes

• Parse commit messages for conventional commit types

• Extract breaking changes

• Group by scope if present

Format Output

• Generate markdown with appropriate headings

• Link to commits and PRs

• Add version header with date

Update CHANGELOG.md

• Prepend new version section

• Maintain existing content

• Update "Unreleased" section

Create New ADR

To document architectural decision:

Generate ADR File

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

Fill Template

• Document context and constraints

• Explain decision rationale

• List consequences and tradeoffs

Review and Commit

• Get team feedback

• Update status to "Accepted"

• Link from main architecture docs

Scaffold New PRD

To create product requirements:

Generate PRD Template

python scripts/create_prd.py "timeline visualization feature"

Complete Sections

• Define problem and goals

• Write user stories

• List requirements

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:

• MAJOR: Breaking changes (incompatible API changes)

• MINOR: New features (backward-compatible)

• 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:

• Extract relevant changelog section

• Add highlights and notable changes

• Include upgrade instructions if needed

• Link to full changelog

• 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