Cross-Repo Conventions Pattern¶

All Feoda projects follow a single source of truth for coding conventions, branching rules, and documentation standards — this Documentation repo.

Architecture¶

Documentation repo (feodasalesadmin/documentation)
  └── tech/development/conventions/
        ├── branch-conventions.md
        ├── code-conventions.md
        └── developer-onboarding.md

Project repo (e.g., feoda-bi)
  ├── .docs/          ← git submodule → Documentation repo
  └── .github/
        └── copilot-instructions.md  ← points Copilot to .docs/ conventions

How It Works¶

Git submodule (.docs/): Each project includes the Documentation repo as a submodule, giving developers and tools direct file access to all conventions.
Copilot instructions (.github/copilot-instructions.md): Points GitHub Copilot to read convention files from .docs/ before generating code, ensuring AI-assisted code follows Feoda standards.
Auto-sync workflow: A GitHub Action in this repo creates PRs in downstream projects to bump the submodule when conventions are updated.

Setting Up a New Project¶

Step 1 — Add the Submodule¶

git submodule add https://github.com/feodasalesadmin/documentation.git .docs
git commit -m "chore: add documentation submodule"

Step 2 — Update Dev Container (if applicable)¶

In .devcontainer/devcontainer.json, ensure the submodule is initialised on container creation:

"postCreateCommand": "git submodule update --init --recursive && npm install"

Step 3 — Create Copilot Instructions¶

Create .github/copilot-instructions.md with:

## Company Conventions (Single Source of Truth)
All Feoda conventions are in the `.docs/` submodule. Always read and follow these:

- **Branch & Git rules:** `.docs/tech/development/conventions/branch-conventions.md`
- **Code & database conventions:** `.docs/tech/development/conventions/code-conventions.md`
- **Developer onboarding:** `.docs/tech/development/conventions/developer-onboarding.md`

Add project-specific details (tech stack, structure, etc.) as needed.

Step 4 — Add to Auto-Sync Workflow¶

In this repo, edit .github/workflows/bump-docs-submodule.yml and add the new repo to the matrix:

strategy:
  matrix:
    repo: [feodadev/feoda-bi, feodadev/new-project]

Step 5 — Update .gitignore¶

Ensure .docs/ is not in .gitignore — it must be tracked as a submodule entry.

Keeping Conventions Updated¶

Developers should run this periodically (or the auto-sync PR handles it):

git submodule update --remote .docs

Current Projects Using This Pattern¶

Project	Submodule Path	GitHub Mirror
Feoda BI	`.docs/`	`feodadev/feoda-bi`