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.

​
Connect documentation to product work

When a product change affects users, make its documentation part of the release plan. The docs can live in the same pull request when code and documentation share a repository, or in a linked pull request when they don’t. The important part is the connection: reviewers should be able to find the relevant product change, and the release shouldn’t depend on someone remembering the documentation later.

​
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 incorporate current changes rather than pulling on an arbitrary schedule.

​
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. 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.