Submodules guide

This guide explains how to work with the ~74 Git submodules that MEGADOC aggregates, including the initial clone, day-to-day updates, the worktree interaction, and the .megadoc/ fallback architecture.

For the automation side (CI workflow that adds submodules from submodules_source.txt), see Submodule management and automation.

---

Initial clone

Submodule contents are gitignored — only .gitmodules is tracked — so a fresh clone has empty submodule directories until you initialize them.

# Clone the repo
git clone https://github.com/optum-tech-compute/ohemr-epic-megadoc.git
cd ohemr-epic-megadoc

# Initialize and fetch all submodules (required after a fresh clone)
git submodule update --init --recursive

Without --init --recursive, mkdocs build will fail because the nav: section in mkdocs.yml uses !include submodules/*/mkdocs.yml directives that resolve to empty directories.

---

Adding new submodules

1. Add the repository URL to submodules_source.txt.
2. Commit and push the change on a feature branch / worktree.
3. The submodule-adder.yml GitHub Actions workflow adds the submodule and opens a PR.
4. Review the generated documentation structure; if the submodule lacks mkdocs.yml or docs/, the .megadoc/ fallback system fills the gap (see below).

---

Updating submodules

# Update all submodules to their tracked branch tip
git submodule update --remote

# Update one specific submodule
git submodule update --remote submodules/specific-repo

Always run mkdocs build --strict after a submodule bump to confirm nav resolution is intact.

---

Submodules and worktrees

Worktrees share submodule object storage via .git/modules/, but on git ≥ 2.40 each linked worktree gets its own per-worktree submodule working tree and HEAD. This has two practical consequences:

• The first worktree to run git submodule update --init --recursive populates .git/modules/ (the shared object DB); subsequent worktrees still need their own git submodule update --init --recursive to materialize the working tree under submodules/<name>, but the fetch is fast because objects are already cached.
• Submodule HEADs are tracked per-worktree, so checking out a different commit in worktree A does not mutate the working tree in worktree B. The real hazard is the shared object DB plus per-worktree HEAD divergence: it is easy to cd into submodules/<name> from one worktree and accidentally push a branch that came from another worktree's checkout. Always confirm git -C submodules/<name> status and the current branch before pushing from inside a submodule directory.

If a submodule appears empty in a new worktree, run git submodule update --init --recursive from inside that worktree's root.

---

Validation and the .megadoc/ fallback system

Some submodules do not yet conform to the required mkdocs.yml + docs/ + docs/index.md structure. MEGADOC has a fallback layer to keep the build green while the upstream repo gets remediated.

• .megadoc/scripts/validate-submodules.py — scans submodules/ for required files and writes a JSON report.
• .megadoc/scripts/apply-fallbacks.py — generates minimal fallback configs in .megadoc/fallbacks/ for any submodule the validator flagged.
• .github/workflows/validate-submodules.yml — runs both scripts in CI and auto-creates GitHub issues against repos missing documentation.

Run the validators locally before pushing a submodule bump:

python3 .megadoc/scripts/validate-submodules.py --output megadoc-validation.json
python3 .megadoc/scripts/apply-fallbacks.py --report megadoc-validation.json
mkdocs build --strict

---

Requirements for submodules

• A docs/ folder with Markdown content
• A mkdocs.yml configuration file
• A docs/index.md landing page
• A README.md at repo root
• Frontmatter on every page (see the writing standards)

Submodules that don't meet these requirements still build via the .megadoc/ fallback layer, but an issue is auto-filed against the upstream repo.

---

Best practices

• Keep submodules updated; stale submodules diverge silently.
• Document any manual integration steps in the submodule's own docs/, not in MEGADOC.
• Always run mkdocs build --strict before opening a PR (this mirrors what the CI docs-quality-check.yml workflow runs).
• Follow naming and organization conventions (see naming and the validators in scripts/).

---

For troubleshooting, see Support and FAQ.