Branching & Pull Request Workflow

This workflow is inspired by Hono’s open source practices and the Conventional Commits standard.

Branch Naming

We use feature-focused, lowercase, kebab-case branch names prefixed by type:

• feat/integrate-calendly
• fix/navbar-overlap
• chore/update-dependencies
• docs/add-pr-guidelines

This keeps history and PRs readable at a glance.

Commit Messages

We follow the Conventional Commits standard:

• feat(login): add Google OAuth
• fix(auth): handle expired JWTs
• chore(deps): bump next.js to 14.2
• docs(readme): update contributing section

Format:
<type>(scope): imperative message

Pull Requests

• Target branch: PRs go to main (or staging if we adopt a staging flow).
• Merging:
  • Never push directly to main.
  • Always open a PR.
  • Branches are deleted after merge to avoid clutter.
• Review & Merge Rules:
  • Code owner merges after approval.
  • Exception: If a PR is blocking another feature and is already approved, another reviewer with write access may merge.

Branch Lifecycle

1. Create a branch from main:
   git checkout -b feat/my-feature
2. Commit changes with proper Conventional Commit messages.
3. Push branch and open a PR:
   git push -u origin feat/my-feature
4. Get review → resolve feedback → approval.
5. Merge via PR → branch auto-deletes.

PR Cadence

• Push early, push often. Small PRs are easier to review, test, and merge.
• Merge frequently. Avoid long-lived branches that drift too far from main.
• Keep main stable. Every merge should be production-ready (tests passing, builds green).
• Use feature flags for incomplete features when needed, so code can be merged without blocking releases.
• Frequent merges help reduce merge conflicts, improve deployment stability, and keep the production environment healthy.

Staging & Releases

• For bigger projects, we may introduce a staging branch:
  • Feature branches merge into staging first.
  • QA and integration testing happen in staging.
• Once changes are verified, staging is merged into main for release.
• Releases on main should include versioning (e.g., v1.2.3) to track production deployments.
• This approach separates integration testing from production-ready code, keeping main stable.

Merging Strategy

We use squash & merge for a clean history.

• Keeps main free of noisy commits.
• Final commit message should summarize the PR in Conventional Commit style.

Example:

• Branch commits:
  • feat(auth): add login page
  • fix(auth): correct redirect
• Squashed into:
  • feat(auth): add login page with correct redirect

Example Repositories

Here are some open-source projects that follow similar branching, PR, and commit conventions:

• Hono – Web framework built on web standards
• ORPC – Remote procedure call library
• Nuxt – Vue framework with staged PRs and clear conventions
• Vitest – Vite-native test framework
• Slidev – Presentation framework for slides with proper PR workflow

---

✅ This ensures:

• Clean commit history
• No orphaned branches
• Predictable, consistent workflow
• Stable production environment through frequent, safe merges
• Optional staging for integration testing and controlled releases