Skip to content

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

@mnriem

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions