Skip to content

Capability 009: Next Steps

Status: Accepted

Context

Some generated artifacts need a step from the developer before their first push succeeds: a Go repository has no go.sum until make init runs, a firmware has no CubeMX code, and a new board has no outline. Without a hint, the developer learns this from a red pipeline, contrary to the goal that the pipeline works from the first commit (mission statement, Head start). This capability names these steps when repo update generates an artifact and in the artifact's README.md.

References

Details

A Next Step is a manual step the developer has to take after generation; without it, a make target or the pipeline of the artifact fails.

Next Steps, by profile:

Profile Next Step
Go, every type Run make init and commit go.sum.
TypeScript frontend-react Run make init and commit package-lock.json.
C++ firmware-stm32 Generate the CubeMX code as described in vendor/cubemx/README.md.
KiCad electronics Draw the board outline on layer Edge.Cuts; make drc fails until then.
Every profile Replace the TODO markers in the generated files.

Output of repo update for a new Go service planner and a new firmware bridge:

next: planner: Run `make init` and commit `go.sum`.
next: bridge: Generate the CubeMX code as described in `vendor/cubemx/README.md`.
next: Replace the `TODO` markers in the generated files.

Section Next Steps of the root README.md of a mono-repository explains how to work in it:

  • Specifications that concern the whole system go to the root specs/: the mission statement, decisions across artifacts, and shared interfaces. Specifications of one artifact go to its own specs/.
  • A new artifact is added with repo add, completed in .repo.yaml, and generated with repo update.

Functional Requirements

  1. repo update prints the Next Steps of each artifact it generates for the first time, one per line, prefixed with next: and the artifact's name.
  2. The Next Step that applies to every profile is printed once per run, without an artifact name.
  3. repo update prints no Next Step for an artifact that meta already records.
  4. Next Steps follow the review: lines (capability 002, Functional Requirement 11).
  5. Section Next Steps of the artifact's README.md lists the artifact's Next Steps, the one for every profile included.
  6. The root README.md of a mono-repository has section Next Steps with the content in Details.

Non-Functional Requirements

None.

Technical Requirements

None.

Error Handling

None.

Out of Scope

  • Steps that are recommended but not required, e.g. devbox shell or make build
  • Setting up credentials and secrets on the forge (capability 006)
  • Next Steps for a module added to an existing artifact
  • repo check; it prints the files only

Acceptance Criteria

  1. Empty Git repository with a Go service planner, repo update: standard output contains next: planner: with make init, and one line with TODO and no artifact name.
  2. Same repository, committed, repo update again: standard output contains no next: line.
  3. Mono-repository with the artifacts planner (Go service) and bridge (C++ firmware-stm32), generated and committed, artifact board (KiCad electronics) added, repo update: standard output contains next: board: with Edge.Cuts, and no next: planner: or next: bridge:.
  4. Java service ledger, repo update: standard output contains no next: ledger: line.
  5. KiCad electronics, generated: section Next Steps of README.md contains Edge.Cuts and TODO.
  6. Mono-repository, generated: section Next Steps of the root README.md contains repo add and specs/.

Decisions

  1. Only steps without which a target or the pipeline fails. A list of recommendations is read once and then ignored; the README describes the rest. Consequence: Java and C++ other than firmware get no Next Step of their own.
  2. Printed when the artifact is first generated, not on every run. repo update runs repeatedly; a repeated hint is noise, and silence on success remains the rule (guideline cli_tool.md). Consequence: a developer who misses the output finds the steps in the artifact's README.md; no command repeats them.
  3. A prefix per line instead of a block, as for review:. The output stays one line per finding and can be filtered with grep. Consequence: no option is needed to silence the output for scripts; commands keep taking no options.
  4. repo update does not run make init itself. Running it would need the toolchain on the generator's host and would mix generation with dependency resolution. Consequence: the Next Step for Go and TypeScript remains a manual step.
  5. How to work in a mono-repository goes to its root README.md, not to the output. Where specifications belong and how an artifact is added are guidance, not steps without which something fails (Decision 1). Consequence: a developer learns it from the README; repo update prints no hint about it.