Skip to content

Release Cadence Lessons

FCC has shipped 20+ releases from v1.0 through v1.7 in roughly two years. This page extracts the operational lessons from that arc: what worked, what hurt, and what would be worth copying for a smaller project.

The arc in one sentence

v1.0 (baseline) → v1.1 (deployment story: Docker, Helm, K8s) → v1.2 (verticals) → v1.3 (docs scale-up, publications, audit tooling) → v1.4 (ecosystem pivot, constellation-vertical GitHub repos, dual-bus events) → v1.5 (six pillars, federation, i18n seed) → v1.6 (seed-data + translations) → v1.7 (in progress).

Each release roughly matched plan. That alone is the first lesson.

Lesson 1: Plans are contracts with your future self

Every FCC release ships with a plan file, usually stored in the maintainer's notes (.claude/plans/...). The plan:

  • Is written before code changes.
  • Names stages.
  • Specifies exit criteria per stage.
  • Is publicly referenced in the release notes.

The cost of writing the plan is an hour or two. The payoff is weeks of avoided drift during execution.

Adaptation: maintain a RELEASE_PLAN.md (active plan only) plus a RELEASE_PLANS_ARCHIVE.md (shipped plans). Refer to them in PR descriptions.

Lesson 2: Patch clusters are fine, sometimes necessary

FCC has a history of rapid patch sequences (e.g., v1.3.5 → v1.3.5.1 → v1.3.5.2 → v1.3.5.3 → v1.3.5.4). These are not failures; they are evidence the project is willing to ship small, verifiable improvements rather than batch everything into a minor.

Rules for healthy patch clusters:

  • Never regress. Every patch passes the full suite.
  • Document the cluster explicitly in release notes.
  • Stop the cluster before its fatigue outweighs its value (usually at 3-5 patches).

Adaptation: if you find yourself wanting to ship three small fixes back-to-back, do it. Do not pretend they are one release.

Lesson 3: Release notes are the spine

A single RELEASE_NOTES.md file, maintained from the first release forward, is load-bearing. It is:

  • The best new-contributor orientation.
  • The journalist's starting point.
  • The audit trail for maintainers.

Anti-pattern: per-release files in a notes/ directory. They fragment the history. One file, prepended to.

Lesson 4: Version numbers carry meaning (or should)

FCC uses semver-ish rules:

  • Major: "reconsider your integration."
  • Minor: "new feature, compatible."
  • Patch: "bug fix, no API change."
  • Four-part (rare): "cluster of small patches during an accelerated window."

When a rule would force a release to be labeled in a confusing way, pick a label that tells the truth even if it is off-spec. For instance, a "patch" that ships significant docs additions but no code change is still a patch; users update without review.

Lesson 5: CI is the release hero

Every FCC release is gated on the full CI suite passing. The suite includes:

  • Unit tests.
  • Integration tests.
  • Coverage gate (currently 99%+).
  • Lint (ruff).
  • Docs build.
  • Ecosystem-registry drift test (since v1.3.5.4).
  • K8s smoke (since v1.2.1).

If CI is green, the release ships. If CI is red, the release waits. No exceptions.

Adaptation: even a two-check CI (test + lint) is better than none. Add more gates as the project matures; never remove one.

Lesson 6: Coverage ratchets work

FCC's coverage gate rose from 94% in v1.2.1 to 99% in v1.2.6 in one-percent increments per patch. The ratchet is simple: CI fails if coverage drops, and contributors who add code must add tests. The gate never goes down.

Adaptation: if your project is at 60% coverage, set the gate at 60%. In the next release, set it at 61%. Over a year you reach 70% without any crash programs.

Lesson 7: Sister projects take discipline, not wishful thinking

FCC has ten constellation-vertical repos plus two sister projects (POLARIS, LYRA). Coordination is not automatic; it is explicit:

  • Each vertical has its own release cycle, but bumps are coordinated at FCC minor boundaries.
  • A vocabulary-provider plugin contract formalizes the interface (see ADR-0001).
  • SHA256-pinned ecosystem registries drift-check against each sister.

If FCC tried to vendor or monorepo these, it would collapse under its own weight. The trick: narrow, versioned interfaces, and ceremonial coordination at release boundaries.

Lesson 8: Stories before code

Roughly every third release introduces a "story" (narrative rationale). For example, v1.4.0's story was "ecosystem pivot"; v1.5.0's story was "six pillars." Each release notes entry opens with the story before listing changes.

Adaptation: for any minor release, spend 30 minutes writing the story before you start coding. Often it reveals that you are actually planning two releases, or that one planned item does not fit the story and should wait.

Lesson 9: Documentation is a release feature

FCC explicitly treats docs additions as release-worthy. v1.3.10 added six audience directories + four guidebook chapters + a cross-link matrix; it was tagged and announced as a release.

Adaptation: when your docs additions accumulate, tag them as a release. Your users will read the notes.

Lesson 10: Rollback plans exist

For every release, answer one question in writing: "If this is bad, how do we roll back?" For most releases the answer is "revert the tag; rerun CI." For some (breaking changes, schema migrations), the answer is longer. Write it down. You will not remember in the crisis moment.

What would not transfer

Not every FCC pattern transfers:

  • Monthly cadence. FCC has full-time attention. Most OSS does not. Quarterly is fine.
  • Five sibling repos plus ten constellations. A single-repo project should not artificially fragment.
  • 99% coverage. Appropriate for a reusable framework. Overkill for a one-person experiment.

Adopt at your own scale.

A readiness checklist for v2.0

FCC has not shipped v2.0 yet. When it does, these will likely be true:

  • All breaking changes are announced one minor in advance.
  • A migration guide exists from v1.7 to v2.0.
  • A compatibility shim is available at least for the following release.
  • The release notes explicitly walk users through expected breakage.

Adaptation: if you ever plan a major, pre-announce. The discipline forces clarity.

Where next

Time to bring it all together: the Further Reading list, or return to the index to plan your adoption path.