Skip to content

docs: add branch naming convention to AGENTS.md and CONTRIBUTING.md #2677

Description

@mnriem

Problem

Branch names across the repository are inconsistent — some use issue-NNNN, others feat/description, fix/NNNN-description, add-description (no number), pr-NNNN, etc. This makes it difficult to:

  • Trace worktrees back to their corresponding issues/PRs
  • Identify merged branches for cleanup (especially with squash merges where git branch --merged doesn't work)
  • Maintain a consistent contributor experience

Proposed Solution

Document a branch naming convention in:

  • AGENTS.md — as a requirement for AI coding agents (they will comply deterministically)
  • CONTRIBUTING.md — as a strong recommendation for human contributors

Convention

<type>/<number>-<short-slug>

Where <number> is either an issue number or a PR number — whichever is created first. This accommodates contributors who start with a PR rather than an issue.

Prefix When to use
feat/ New features
fix/ Bug fixes
docs/ Documentation changes
community/ Community catalog additions
chore/ Maintenance, tooling, CI

Rules:

  1. Always include the issue or PR number immediately after the prefix
  2. Use kebab-case for the slug
  3. Keep the slug short — enough to identify the work without looking up the issue

Acceptance Criteria

  • AGENTS.md has a "Branch Naming Convention" section (requirement for agents)
  • CONTRIBUTING.md references the same convention in the "Submitting a pull request" section (recommendation for humans)
  • The PR's own branch follows the documented convention

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions