FairGarden Distribution

Version 0.1.0-alpha.8

Ship a set of versioned modules together.

End users do not care about semver — they want to know how old their copy is, and 2024.12.01 says that at a glance where 1.2.1 does not. Developers do care, because semver says how much work an upgrade will be. A distribution uses each where it belongs: the distribution is versioned by date, the modules inside it by semver.

@fairgarden/core  2024.12.01
  @fairgarden/id          1.2.3
  @fairgarden/design      1.5.6
  @fairgarden/membership  1.0.0

Modules are git submodules, so the commit is the pin and the version is whatever the module's own package.json says. Nothing in the distribution repository restates it.

Documentation

The docs are a site in this repository. Run them with:

pnpm --filter @fairgarden/distribution-docs dev

• Versioning — why two schemes, where a version comes from, and LTS branches
• Modules — apps, packages, and how they resolve
• Extending — one distribution built on another
• Deploying — one deployment, or many
• Running it — dev modes, and a hostname per app
• Growing a module — building in place, then extracting
• Policies — the organization's rules, on every module's own, built once
• Releasing a module — semver, maintenance branches and dist-tags
• Submodule urls — what a build host can actually clone
• Commands and Functions — the fg-dist CLI and its API

Install

pnpm add -D @fairgarden/distribution

Or scaffold without installing anything:

pnpx @fairgarden/distribution init distribution acme --name @acme/core

fg-dist init <kind> [dir]    # scaffold a distribution, monolith or module
fg-dist add-module <url>     # add a module repository as a submodule
fg-dist extract <path>       # turn a directory here into its own repository
fg-dist sync                 # what has moved, and whether the floor holds
fg-dist bump [name...]       # take the newest non-major version
fg-dist check                # fail when this ships older than what it extends
fg-dist use-https            # rewrite ssh submodule urls, and check they are public
fg-dist readme               # write the module versions into the readmes
fg-dist overrides            # resolve modules from the tree, not the registry
fg-dist workflows            # give every module a publishing workflow
fg-dist policy build         # the organization's policy, on every module's own
fg-dist policy use           # give this service its copy, in its build
fg-dist canary               # stamp a canary version, for CI
fg-dist release --minor      # open the next version on main, and a branch behind it
fg-dist prerelease --major   # start the next line on a branch, leaving main alone

Mounting a distribution's apps into one Next deployment is a separate concern, handled by @fairgarden/monolith.

Releasing

This module releases on its own. 0.1.0-alpha.8 is what main is working towards, not what is published — the version here is always the next one. Its release notes are the top section of CHANGELOG.md, where every pull request adds a line linking itself.

1. Publish it. Run the Publish workflow from the Actions tab, picking the dist tag. It refuses if that version is already on npm. Once it is out, open pull requests are held — their changelog check fails — so nothing is noted under a version that has already shipped.
2. Start the next version. pnpm next-version opens a pull request moving main to 0.1.0-alpha.9 and starting its section of the changelog, or pnpm next-version --id rc to change identifier. Merging it lifts the hold. A prerelease gets no maintenance branch; there is no released line behind it yet.

A held pull request goes on once it is brought up to date with main and its line is moved into the new version's section.

Every push to main publishes @fairgarden/distribution@canary. A canary is not a release and carries no promise; it is there so main can be tried without a checkout.