GitHub workflow

This guide explains the standard GitHub workflow for contributing to MEGADOC, including the mandatory worktree pattern, feature branching, pull requests, review, and merge process.

---

Prerequisites

• Cloned the ohemr-epic-megadoc repository locally.
• Local Python venv set up and requirements.txt installed (see Local Development Setup).
• The base clone stays on main at all times. All feature work happens in a worktree under worktrees/.

---

Step-by-step process

1. Create a worktree for your change. Never work directly on the main checkout. Slashes in branch names map to hyphens in the worktree folder (feature/foo becomes worktrees/feature-foo).

   # From the repo root, which must be on main
   git branch --show-current   # must print: main
   
   # Ensure worktrees/ is gitignored
   grep -q '^worktrees/' .gitignore || echo 'worktrees/' >> .gitignore
   
   # Create branch + worktree in one step
   git worktree add worktrees/feature-azure-vm-troubleshooting -b feature/azure-vm-troubleshooting main
   cd worktrees/feature-azure-vm-troubleshooting
   

   • Use descriptive branch names (for example, feature/azure-vm-troubleshooting-guide).
   • Verify location: pwd must contain /worktrees/ before any further git operation.

2. Make your changes.

   • Edit or add documentation files.
   • Use mkdocs serve for live preview at http://127.0.0.1:8000.
   • Follow Writing Standards.

3. Validate locally before pushing. Run the same checks docs-quality-check.yml runs in CI:

   # Build the site (CI uses bare `mkdocs build` and treats only docs/ warnings
   # as blocking; for local dev, --strict surfaces every issue early)
   mkdocs build --strict
   
   # Frontmatter coverage report (same script the CI uses)
   bash scripts/analyze-frontmatter-by-dir.sh
   
   # Pre-commit hooks (frontmatter, naming, code-block, link checks all run here)
   pre-commit run --all-files
   

4. Commit your work. Use Conventional Commits only — this repo's conventional-commits ruleset rejects non-canonical prefixes. Pass real newlines via repeated -m flags or a heredoc; literal \n inside git commit -m "..." is not interpreted by bash.

   git add docs/getting-started/azure-vm-troubleshooting.md
   git commit -m "docs(getting-started): add Azure VM troubleshooting guide" \
              -m "- Add troubleshooting steps" \
              -m "- Include error scenarios" \
              -m "- Add diagnostic commands"
   

5. Push and open a pull request.

   git push -u origin feature/azure-vm-troubleshooting
   gh pr create --fill   # or fill in title/body manually
   

   • Include description, testing notes, and screenshots where relevant.
   • Link related issues with Closes #<n> so they auto-close on merge.

6. Wait for the docs-quality-check workflow. The PR runs three stages:

   1. validate-changed-content — frontmatter, link, naming, and code-block checks on changed files only.
   2. build-and-validate — full mkdocs build --strict with submodule checkout. Only docs/ warnings are blocking; submodule warnings are informational.
   3. quality-gate — final gate; both prior stages must pass.

   Inspect status with gh pr checks <pr-number>.

7. Review and merge.

   • At least one reviewer required (see branch protection below).
   • Address feedback by amending commits on the same branch — do not open follow-up PRs unless asked.
   • CI checks must pass before merge.

8. Clean up the worktree after merge.

   cd /path/to/repo                           # main clone
   git worktree remove worktrees/feature-azure-vm-troubleshooting
   git fetch --prune
   

---

Branch protection rules (megadoc repo)

• No direct pushes to main.
• All changes via pull requests.
• Minimum 1 review required for this repository (other repos in the org may require more — always check the target repo's branch protection).
• All CI checks must pass.
• Squash-merge is not enforced; prefer the project's configured strategy.

---

For more on publishing and deployment, see Publishing Process.