Skip to main content
Git gives everyone a place to work. It doesn’t decide who should review a change, whether two projects overlap, or what the final wording should be. Those parts still need a team.

​
Make the pull request easy to review

A useful pull request tells reviewers:
  • What changed
  • Why it changed
  • Which pages or flows deserve close attention
  • What is deliberately outside the scope
The diff should support that story. Separate unrelated work, remove temporary files, and explain changes that aren’t obvious from the rendered page. Ask people for the feedback they are equipped to give. An engineer may verify technical behavior, a writer may focus on clarity and structure, and a product manager may confirm scope or terminology. For a small correction, one reviewer may cover everything. When a docs change goes with a product change, link the two pull requests so reviewers can check the docs against what actually shipped.

​
Review in the web editor

Not everyone on your team needs to use GitHub. In the web editor, teammates can:
  • Comment on specific text or a whole page. Every role can comment, including viewers.
  • Suggest changes that an editor or admin accepts or rejects. Viewers are always in suggesting mode.
  • Edit together on the same branch in real time, in visual or source mode. Changes merge automatically as you type, with no conflicts to resolve.
Comments stay in the editor and never reach your repository. If the branch has an open pull request on GitHub, Mintlify adds a summary of unresolved comment threads to the pull request description, so reviewers on both sides see the same open questions.

​
Coordinate before branches overlap

Two branches can change the same files without causing a conflict. A conflict occurs only when Git can’t combine overlapping edits automatically. Still, Git resolving the files doesn’t guarantee that the combined writing makes sense. Two writers can add contradictory explanations in different paragraphs and produce a clean merge. Tell teammates when you’re changing a shared page or navigation group, and review the combined result after syncing. Keep branches focused and start them from a current deployment branch. For longer work, agree on checkpoints where you’ll bring in the latest changes, rather than doing it on an arbitrary schedule. If someone pushes to the repository while you have a page open in the web editor, the editor merges their changes into your page and tells you. When both of you changed the same part of the page, it keeps both versions and highlights them so you can choose.

​
Resolve a merge conflict locally

Before bringing main into your feature branch, confirm where you are and that your own work is committed or safely set aside:
Replace main if your site uses another deployment branch. If Git finds a conflict, it marks the affected section:
Edit the section into the final version you want and remove all three marker lines. Then preview the page and finish the merge:
Don’t choose a side based only on which version is newer. Read the surrounding page and preserve the intent of both changes when appropriate.

​
Use branch protection as a team rule

Branch protection can require pull requests, approvals, or passing checks before changes reach the deployment branch. Configure the rules around the risks your team wants to manage. Mintlify follows those rules. When the deployment branch is protected, the web editor won’t publish to it directly. It offers Create branch instead, so every change goes through a pull request. If your repository requires pull requests, use the same path for urgent fixes but keep the review focused and quick. If it permits direct publishing, decide as a team which changes still deserve a branch and preview.

​
Protect work before trying to undo it

Start with git status and git diff. These commands inspect the working copy without changing it. If you need to switch tasks, commit a sensible checkpoint or stash the work temporarily:
Return to the branch later and run git stash pop. Review the result because applying a stash can also produce conflicts. git restore path/to/file.mdx discards uncommitted changes to that file. Use it only when you have inspected the diff and are certain those edits are unwanted. It isn’t a recovery command. If a mistake is already in shared history, prefer a new commit that corrects or reverts it. Avoid rewriting a branch other people may be using unless your team has agreed to it. That’s the end of the Git and GitHub for Mintlify course. You can now connect the repository, make a focused change, review the rendered result, and recover when work overlaps. Next, Structure docs that scale covers how to organize that content as the documentation grows.