Skip to main content
A useful branch represents one reviewable outcome. Someone looking at its name and pull request should be able to answer, “What will this change accomplish?” Your team’s workflow determines when a branch is required. Repositories with protected deployment branches require pull requests; teams with a direct-publishing workflow may handle small fixes differently.

​
Give the branch one job

Good branch scopes include:
  • Add an authentication quickstart
  • Correct the webhook examples
  • Reorganize the API navigation
Avoid mixing unrelated cleanup into the same branch. If you notice a typo while restructuring the API navigation, record it for a separate fix unless it must change for the restructuring to work. Focused branches produce focused pull requests. They’re easier to describe, review, revise, and revert if something goes wrong.

​
Name it for the outcome

Use a short, specific name with lowercase letters and hyphens:
  • add-auth-quickstart
  • fix-webhook-examples
  • reorganize-api-navigation
Names such as updates, ethan-edits, and docs-fixes don’t tell a teammate what is in the branch. Two to five meaningful words is often enough, but clarity matters more than a fixed length. Follow an existing team convention if the repository uses issue numbers or prefixes such as docs/.

​
Start from the current deployment branch

Before creating a local branch, update the branch your site deploys from. This example uses main:
Starting from a current base reduces the chance that your pull request includes old changes or encounters avoidable conflicts. In the web editor, select the deployment branch before creating the new branch.

​
Keep the branch understandable

Commit coherent checkpoints and push the branch when you want to share or back up the work. If the branch’s purpose grows from “fix one example” into “rewrite the entire API section,” stop and decide whether the new work deserves another branch. Long-running work isn’t automatically wrong. A migration or product launch may take time. Keep it manageable by merging independent groundwork separately and syncing the remaining branch with the deployment branch when needed.

​
Merge and clean up

Before merging, confirm that:
  • The pull request still matches the branch’s stated purpose
  • The preview renders the intended pages and navigation
  • Required reviews and configured checks have passed
  • No unrelated files slipped into the diff
After merging, delete the feature branch unless your team has a reason to keep it. Deleting it doesn’t remove the merged work or its commit history. Next up: Preview deployments — review the rendered result, not just the changed lines.