> ## Documentation Index
> Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Best practices for branches
> When to create a branch, how to name it, and what the lifecycle looks like from first edit to merged change.
export const Quiz = ({question, answers, correctFeedback, incorrectFeedback}) => {
const [selected, setSelected] = React.useState(null);
const [checked, setChecked] = React.useState(false);
const quizId = React.useId();
const isCorrect = checked && answers[selected]?.correct;
const reset = () => {
setSelected(null);
setChecked(false);
};
return
;
};
You already know what a branch is conceptually — a separate workspace where you can make changes without affecting the live site. This lesson is about using branches in practice: when to create one, what to call it, and how to manage it through to completion.
## When to create a branch
The rule is simple: any time you start a new piece of work, create a new branch.
That includes small changes. It's tempting to edit a single typo directly on main, but that bypasses the review step and skips the preview deployment. Even minor changes benefit from going through a pull request — it takes an extra thirty seconds and gives you a preview link to verify the change looks right before it goes live.
The web editor handles this automatically — when you publish from the editor, Mintlify creates a branch and opens a pull request on your behalf. If you're working locally with the CLI, you create the branch yourself before you start editing.
## How to name a branch
Branch names should describe the work being done. A name like `update-authentication-guide` tells your teammates what's changing. A name like `ethan-edits` or `updates` tells them nothing useful.
A few conventions that work well for documentation:
* Use lowercase letters and hyphens: `add-quickstart-page`, not `Add Quickstart Page`
* Be specific enough to distinguish from other work: `fix-api-reference-broken-links` rather than just `fix-links`
* Keep it short enough to type without pain — two to five words is usually right
You don't need a naming convention that's enforced by tooling. Something consistent enough that any teammate can glance at a branch list and understand what each one is for is sufficient.
## The branch lifecycle
Every branch follows the same lifecycle:
Start from an up-to-date copy of main. If you're working locally:
```bash theme={null}
git checkout main
git pull
git checkout -b your-branch-name
```
This ensures your branch starts with the latest version of the live docs, which reduces the chance of conflicts later.
Edit your files, then save your progress with a commit. Commit as you go — you don't have to wait until everything is finished.
```bash theme={null}
git add .
git commit -m "Add authentication quickstart"
```
Each commit is a checkpoint you can refer back to. A series of focused commits is easier to review than one large commit at the end.
When you're ready for review, push your branch to GitHub and open a pull request.
```bash theme={null}
git push origin your-branch-name
```
GitHub will prompt you to open a PR. Mintlify automatically generates a preview deployment as soon as the PR is open.
Once the PR is approved and merged, delete the branch. It's done its job, and leaving stale branches around makes it harder to see what work is actually in progress.
GitHub offers a **Delete branch** button immediately after merging. One click and it's gone.
## Keep branches short-lived
A branch that stays open for a week is a branch that's drifting further from main every day. The longer it lives, the more likely it is that someone else has merged conflicting changes.
The fix is to keep branches small and focused. A branch that does one thing — adds one page, fixes one section, updates one set of links — can be opened, reviewed, and merged quickly. A branch trying to do everything takes longer to review and has more surface area for things to go wrong.
If you find yourself working on a large restructuring project, break it into a sequence of smaller PRs. Each one should leave the docs in a better state than it found them, even if the full project isn't finished yet.
Next up: [Preview deployments](/courses/git-github/mintlify-previews) — how Mintlify generates a live preview for every pull request, and how to use it to catch problems before they reach users.