Skip to content

UC005: Initialize a Mono-Repo With Multiple Artifacts

Overview

Property Value
ID UC005
Level User Goal
Primary Actor Developer
Trigger Developer wants to scaffold several related artifacts (e.g. services and a frontend) into one Git repository
Precondition Target repository contains a .mono-repo.yaml manifest and no --name flag is passed to repo init
Success Guarantee Every entry in the manifest's repos: list is populated in its own subdirectory, each with its own .repo.yaml
Related Rules BR-018, BR-019, BR-020, BR-021, BR-022, BR-023, BR-024, BR-025, BR-001, BR-002, BR-004, BR-005, BR-006, BR-007

Related Features:

Goal

  • What problem does this use case solve?
  • Populates one Git repository with several artifacts described in a single .mono-repo.yaml manifest, each generated exactly as UC001 would generate it standalone
  • Lets a developer describe a mono-repo (e.g. a service bundled with its frontend, or firmware paired with production files) declaratively instead of invoking repo init once per artifact by hand
  • Each entry keeps its own independent CI pipeline, composed into the mono-repo's overall CI without job-name/tag/registry collisions, and triggered only when that entry's own subdirectory changed (see ADR-012)
  • Scaffolds a small root-level specs/ for content that spans more than one artifact — system-wide ADRs and business rules — alongside, not instead of, each entry's own full specs/ tree (see ADR-013)
  • What does it explicitly NOT do (scope boundary)?
  • Generate complete, production-ready software artifacts (same boundary as UC001)
  • Change how a single artifact is generated or updated — each entry uses the exact same generation pipeline and .repo.yaml format as UC001/UC002
  • Render copyrightStatement/authors into generated file headers — these manifest fields are accepted and validated, but rendering them is a deferred future capability (see mono_repo_spec.md)
  • Support per-entry CI override — all entries share the manifest's single ci value
  • Keep .mono-repo.yaml in sync with the .repo.yaml files it produces — the manifest is a one-time generation input, not modified by generation (see ADR-011)

Transaction Boundary

No transaction. Generator writes files, one artifact (subdirectory) at a time, in manifest order. In case of failure partway through, entries already generated remain on disk; entries not yet reached are not created. This mirrors UC001's own no-transaction guarantee, applied once per entry.

Sequence Diagram

Not applicable

Further Details

For the main success scenario, extensions (alternate flows), and BDD scenarios, refer to the corresponding feature file (BDD specification and executable test).