Skip to main content

New Module

A module lives in its own repo, is versioned and tagged independently, and is consumed by apps as a git submodule pinned to a tag.

1. Create the repo​

CLUSTER-MODULES project, workspace clustersco. Name uses underscores and matches the module directory it becomes (bgv_templates, not bgv-templates). Single trunk develop; protect it.

  • Track its db_version (its DB migration number); apps record this in their version.yml.
  • Keep the module self-contained — no app-specific coupling.

2. Delivery wiring​

  • Jira Component whose name mirrors the Compass service name; set a Component Lead. (Modules are Components, not their own Jira projects.)
  • Compass service entry (ownership, dependencies). See Governance.

3. Release it (so apps can pin it)​

Cut a release on the module's develop and tag it (SemVer, annotated, no v) — e.g. bgv_templates 1.4.0. Push the module tag before any app references it.

4. Submodule it into the apps that need it​

git submodule add git@bitbucket.org:clustersco/bgv_templates.git modules/bgv_templates
git -C modules/bgv_templates checkout 1.4.0        # the released TAG
# record its db_version in the app's version.yml, then:
git add .gitmodules modules/bgv_templates version.yml
git commit -m "BGV-233 Add bgv_templates 1.4.0"

Resolve a gitlink conflict by checking out the intended tag inside the submodule — never --ours/--theirs.

5. Updates flow automatically​

Tagging a new module version fires a webhook → each subscribing app's Bitbucket Pipeline opens an automated "bump bgv_templates → x.y.z" PR (advances the submodule pointer + db_version, merges on 1 approval + green CI, re-assembles, re-releases). A module change never lands in an app silently.

Checklist​

  • Repo in CLUSTER-MODULES, underscore name, develop protected
  • db_version tracked; module is self-contained
  • Jira Component (mirrors Compass) + Lead · Compass entry
  • First tag pushed (before any app pins it)
  • Submoduled + pinned at a tag in each consuming app; version.yml updated