Changelog Process

This document describes how PrompTrek uses conventional commits to automatically generate changelogs.

Overview

PrompTrek uses Conventional Commits specification to automatically generate and maintain a changelog. This ensures consistent commit messages and provides a clear history of changes for users and contributors.

Conventional Commit Format

All commits should follow this format:

type(scope): description

[optional body]

[optional footer]

Types

Scopes

Examples

feat(adapters): add support for Visual Studio Code extension
fix(parser): handle empty instructions gracefully
docs(readme): update installation instructions
refactor(core): simplify variable substitution logic
test(cli): add integration tests for generate command
chore(deps): update dependencies to latest versions
ci(changelog): add automated changelog generation

Breaking Changes

For breaking changes, add BREAKING CHANGE: in the footer or use ! after the type:

feat(core)!: remove deprecated API methods

BREAKING CHANGE: The old `generatePrompt` method has been removed. Use `generate` instead.

Automation

Changelog Generation

Changelogs are automatically generated and updated:

  1. On Releases: The release workflow generates changelog entries
  2. On Main Branch: Push to main branch updates the changelog
  3. Manual: Use scripts/generate-changelog.sh for local testing

Configuration Files

Local Development

Generating Changelog Locally

# Generate changelog from git history
./scripts/generate-changelog.sh

# Or manually with conventional-changelog
npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

Release Process

The automated release process:

  1. Tag Creation: Create a version tag (e.g., v1.0.0)
  2. Changelog Update: Automatically generate changelog entries
  3. GitHub Release: Create release with changelog content
  4. PyPI Publish: Publish package to PyPI

Best Practices

Writing Good Commit Messages

  1. Be descriptive: Clearly explain what the change does
  2. Use imperative mood: “add feature” not “added feature”
  3. Reference issues: Include issue numbers when relevant
  4. Keep it concise: Subject line should be under 50 characters
  5. Add body when needed: Explain the “why” in the body

Examples of Good Commits

feat(cli): add --output-dir option to generate command

Allows users to specify a custom output directory for generated files.
This addresses the need for better control over file placement.

Closes #123

fix(parser): handle malformed YAML files gracefully

Previously, the parser would crash on invalid YAML. Now it provides
a helpful error message and suggests fixes.

docs(contributing): add conventional commit guidelines

Helps new contributors understand our commit message format and
expectations for changelog automation.

Examples of Poor Commits

# Too vague
fix: bug fix

# Missing type
update readme

# Wrong format
FIX(parser) - fixed issue with variables

# Not imperative mood
fixed the bug in parser
added new feature to CLI

Troubleshooting

Common Issues

  1. Commit validation fails: Check that your commit message follows the conventional format
  2. Changelog not updating: Ensure commits are properly formatted and include the right types
  3. Missing scope: Add appropriate scope from the approved list

Getting Help