Skip to main content

Git Workflow & Team Collaboration Rules

1. The Core Principle: "Main is Truth"​

Our main branch is the gold standard. It must always be in a deployable state. We do not use develop or stable branches. We use Short-Lived Feature Branches.

2. Branch Naming Convention​

All branches must be prefixed with their intent:

  • feature/ : New functionality or content.
  • fix/ : Bug fixes.
  • refactor/: Code/Folder restructuring with no new logic.
  • chore/ : Documentation, dependencies, or config updates.

Example: feature/add-search-bar or refactor/move-assets-folder

3. The 5-Step Workflow​

Step 1: Sync​

Before starting, always ensure your local main is up to date.

git checkout main
git pull origin main

Step 2: Branch​

Create a descriptive branch. Keep the scope small.

git checkout -b feature/your-description

Step 3: Atomic Commits​

Commit often with clear messages. If you are restructuring, separate "moving files" from "editing code" into different commits.

git add .
git commit -m "refactor: move /docs to /content/docs"

Step 4: The Pull Request (PR)​

Push your branch and open a PR to main on GitHub.

  • Rule: You must run npm run build locally before opening a PR.
  • Rule: If working in a team, at least one other person must "Approve" the PR.
  • Rule: If conflicts exist, merge main into your branch to solve them.

Step 5: Merge & Clean​

Once approved and the build passes:

  1. Merge the PR into main.
  2. Delete the branch from GitHub and your local machine.
git branch -d feature/your-description

4. Conflict Resolution Rule​

We do not REBASE. To keep a transparent history of how conflicts were solved, always use merge:

  1. git checkout feature/your-branch
  2. git merge main
  3. Resolve conflicts in your editor.
  4. git commit and git push. `

5. Production Releases​

To mark a version as "Stable" or "Production Ready," we use Tags:

git tag -a v1.0.0 -m "Description of release"
git push origin v1.0.0

Pro-Tip for Docusaurus Teams​

In your package.json, I recommend adding a "pre-commit" hook or a specific script that checks for broken links. It ensures that no one merges a restructure that breaks the documentation.

**Would you like me to provide the code for a GitHub Action that automatically blocks a