Our Git Workflow
Contributing Guide

Core rules

1. Use your own GitHub account. Never commit under a shared/company login. Every commit must be traceable to a person.
2. Never push directly to main. All changes go through a Pull Request.
3. Every PR needs at least 1 approval before merging.

Branching

Branch off the latest main:

git checkout main
git pull
git checkout -b feature/short-description

Branch naming:

• feature/ — new functionality (e.g. feature/user-export)
• fix/ — bug fixes (e.g. fix/login-redirect)
• chore/ — maintenance, deps, config (e.g. chore/update-eslint)
• docs/ — documentation only

Keep names short and lowercase, words separated by hyphens.

Workflow per task

1. Create a branch off main.
2. Commit your work.
3. Push the branch and open a Pull Request.
4. Get at least 1 review/approval.
5. Merge the PR.
6. Delete the branch after merge.

Self-merging after an approval is fine. The goal is a second pair of eyes, not bureaucracy.

Commit messages

Loose Conventional Commits — enough to skim history, not something to obsess over:

feat: add CSV export to dashboard
fix: correct timezone on report dates
chore: bump dependencies
docs: update setup instructions

Format: type: short summary in present tense. Common types: feat, fix, chore, docs, refactor, style, test.

Secrets & ignored files

• Never commit secrets — .env, API keys, credentials, tokens.
• Use .env.example with placeholder values to document required env vars.
• Make sure .gitignore covers .env, build artifacts, and local config.
• If you accidentally commit a secret, rotate it immediately — removing it from a future commit does not remove it from history.

Deployments

Several repos auto-deploy on push to main (e.g. Railway services like mikesblog-rocket). Keep this in mind:

• Merging to main may trigger a live deployment. Treat main as production.
• This is exactly why we use the branch + PR flow — so nothing untested lands on main by accident.

Pull Request checklist

Before requesting review:

• Branch is up to date with main
• No secrets or .env files included
• Code runs locally
• PR description explains what and why