Skip to main content

​
PR and Commit Workflow

Last Verified: 2026-05-03
PR and commit conventions vary across the Equa repositories. The equabot-gateway repo has the most formalized workflow. equa-web and equa-server follow informal conventions that have not been standardized. This document describes what is currently practiced.

​
Workflow Overview

Source: GitHub Actions workflow trigger configs across repos

​
Branch Naming

​
equabot-gateway (Formalized)

Follows a descriptive prefix pattern: Source: equabot/CLAUDE.md commit and PR guidelines

​
equa-web

Observed patterns from branch history:
  • issue-* for issue-driven branches (e.g., issue-35-thread-detail-view)
  • feat/**, fix/**, docs/**, chore/**, ci/**, and phase-* for active work
  • main as the current PR target in the primary CI workflow
Source: GitHub Actions trigger config (equa-web/.github/workflows/ci.yml)

​
equa-server

  • staging as the primary development branch
  • main as the stable branch
  • prod-deploy as a legacy CI trigger tied to the Cloud Build / Cloud Run path that still exists in the repo
Source: GitHub Actions trigger config (.github/workflows/ci.yml)

​
Commit Messages

​
equabot-gateway (Formalized)

Uses concise, action-oriented messages following Conventional Commits style:
Rules:
  • Start with the affected area/module (e.g., CLI:, Gateway:, Auth:)
  • Use imperative mood (“add”, “fix”, “update” — not “added”, “fixed”)
  • Keep the first line under 72 characters
  • Group related changes; avoid bundling unrelated refactors
Source: equabot/CLAUDE.md “Commit & Pull Request Guidelines”

​
equa-web / equa-server (Informal)

No documented commit message format. Observed patterns include freeform descriptive messages. No enforced convention.

​
Creating a Pull Request

When creating a PR, include:
  1. Summary of scope — What does this PR change and why?
  2. Testing performed — How was this tested? (manual, unit tests, E2E)
  3. User-facing changes — Does this affect what users see? New flags, UI changes, API changes?
  4. Screenshots — If the change has UI impact, include before/after screenshots

​
equabot-gateway PR Process

The equabot-gateway repository has the most detailed PR process:
  1. Create a feature branch from main
  2. Make changes, commit with scoped messages
  3. Run the full gate locally: pnpm lint && pnpm build && pnpm test
  4. Push and open a PR
  5. PR reviewed — goal is to merge, not to block
  6. Prefer rebase when commits are clean, squash when history is messy
  7. After merging, add a changelog entry with PR number
Source: equabot/CLAUDE.md “PR Workflow (Review vs Land)“

​
Other Repositories

No formal PR template or process documented. Follow the general checklist above and request review from a team member familiar with the affected code.
No .github/PULL_REQUEST_TEMPLATE.md was found in equa-web or equa-server. Adding PR templates would help standardize the review process.

​
Code Review

​
What Is Known

  • equabot-gateway: Reviews aim to merge. Reviewers check via gh pr view/gh pr diff. When merging PRs from external contributors, add them as co-contributors and update the changelog.
  • equa-web / equa-server: Code review practices are not formally documented. Reviews happen on an ad-hoc basis.

​
What Needs Standardization

  • Number of required approvals per repo
  • Branch protection rules (currently not documented)
  • Review turnaround expectations
  • Automated review checks beyond CI

​
Merge Strategy

​
equabot-gateway Merge Details

From equabot/CLAUDE.md:
  • Rebase when commits are clean and tell a coherent story
  • Squash when the commit history is messy or contains WIP commits
  • When squashing, add the PR author as a co-contributor
  • After merging, add a changelog entry including the PR number and a thank-you to the contributor
  • If a new contributor, add their avatar to the README contributors section

​
Recommendations

  1. Create PR templates for equa-web and equa-server (.github/PULL_REQUEST_TEMPLATE.md) with a standard checklist
  2. Adopt a commit message convention across all repos (Conventional Commits or the scoped format used in equabot-gateway)
  3. Document branch protection rules and required review counts
  4. Standardize merge strategy — consider rebase-first across all repos for cleaner git history
  5. Add pre-commit hooks to equa-web and equa-server (equabot-gateway already uses prek install for pre-commit checks)