> ## Documentation Index > Fetch the complete documentation index at: https://docs.equa.cc/llms.txt > Use this file to discover all available pages before exploring further. # PR and Commit Workflow > How to branch, commit, and merge code across Equa repositories # 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 | Repository | Formalized? | Primary Branch | CI Triggers | | ----------------- | ----------------------------- | -------------- | --------------------------------------------------------------------------------------------- | | equabot-gateway | Yes (documented in CLAUDE.md) | `main` | Push to `main`; PRs | | equa-web | Informal | `main` | Push to `main`, `feat/**`, `fix/**`, `docs/**`, `chore/**`, `ci/**`, `phase-*`; PRs to `main` | | equa-server | Informal | `staging` | Push to `main`, `staging`, `prod-deploy`; PRs to `main`/`staging` | | equa-patternlib | Informal | `staging` | Push to `staging` | | command-center-so | Informal | `main` | Push/PR to `main` | Source: GitHub Actions workflow trigger configs across repos ## Branch Naming ### equabot-gateway (Formalized) Follows a descriptive prefix pattern: | Prefix | Usage | Example | | -------- | ----------------- | -------------------------------- | | `fix/` | Bug fixes | `fix/364-tab-group-title` | | `feat/` | New features | `feat/voice-call-support` | | `issue-` | Issue-driven work | `issue-42-github-issues-adapter` | 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: ``` CLI: add verbose flag to send Gateway: fix session reconnection on timeout Auth: migrate to OAuth 2.1 PKCE flow ``` **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 | Repository | Preferred Strategy | Rationale | | --------------- | -------------------------------- | -------------------------------------- | | equabot-gateway | Rebase (clean) or Squash (messy) | Maintains linear history when possible | | equa-web | Merge commits (observed) | No documented preference | | equa-server | Merge commits (observed) | No documented preference | ### 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)