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/. In the web editor, you give a branch a title instead, like “Add authentication quickstart.” The same advice applies: describe the outcome. If you leave the title blank, the editor names the branch after the date, which tells your teammates nothing. You can rename the branch later, but that only changes the title shown in the editor and on the pull request, not the underlying Git branch name.

​
Start from the current deployment branch

Before creating a local branch, update the branch your site deploys from, as shown in the workflow lesson. Starting from a current base reduces the chance that your pull request includes old changes or runs into avoidable conflicts. In the web editor, switch to 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 a merged branch doesn’t remove the merged work or its commit history. It does remove the branch’s preview deployment the next time Mintlify syncs. Be careful deleting a branch that isn’t merged. In the web editor, deleting a branch closes its pull request and permanently removes the branch along with any unpublished changes. Next up: Preview deployments—review the rendered result, not just the changed lines.