addy-git-workflow-and-versioning

Use the format "type: short description" with types like feat, fix, refactor, test, docs, or chore. The body should explain why the change was made, not what changed, since the diff already shows that. Each commit should do one logical thing.

Run git worktree add with a target directory and branch name to create a separate working directory per branch. Multiple agents or developers can work simultaneously without branch switching, and failed experiments are removed with git worktree remove.

Trunk-based development keeps main always deployable with short-lived feature branches merging within 1-3 days, while gitflow uses long-lived development branches. DORA research correlates trunk-based development with high-performing teams, though commit discipline matters more than the specific model.

Bump major for breaking changes requiring consumers to modify their code, minor for backward-compatible new functionality, and patch for backward-compatible bug fixes. When unsure whether a change is breaking, assume it is, since a surprise major is cheaper than a broken consumer.

Commit messages are written for developers, while a changelog answers "what changed and do I care?" for consumers. It should be curated, grouped by Added, Changed, Fixed, Deprecated, Removed, and Security, and written in the same change that introduces it.

Never commit build output like dist/ or .next/, environment files like .env, or dependency directories like node_modules/. Set up a .gitignore immediately covering node_modules/, dist/, .env, .env.local, and *.pem to prevent leaking secrets.