docs/decisions/0003-use-git-submodules.md

ADR-0003: Use Git Submodules for External Projects

Status: Accepted Date: 2025-01-27 Deciders: Workspace maintainers

---

Context

We need to include external projects or existing repositories in monorepos. Options include:

• Git submodules
• Copying code into monorepo
• Converting to workspace packages

---

Decision

We will use Git submodules for:

• External repositories
• Existing projects that should maintain independent versioning
• Projects maintained separately

We will use workspace packages for:

• New shared code
• Internal libraries
• Code that benefits from unified versioning

---

Consequences

Positive

• ✅ Maintains repository independence
• ✅ Allows independent versioning
• ✅ Preserves git history
• ✅ Easier external contribution

Negative

• ⚠️ Submodule complexity
• ⚠️ Requires submodule management knowledge
• ⚠️ Can complicate workflow

---

Status: Accepted