Commands
- Running commands - (Outline, Contents)
- init - (Outline, Contents)
- add-module - (Outline, Contents)
- extract - (Outline, Contents)
- sync - (Outline, Contents)
- bump - (Outline, Contents)
- check - (Outline, Contents)
- inherit - (Outline, Contents)
- readme - (Outline, Contents)
- verify - (Outline, Contents)
- migrate - (Outline, Contents)
- env - (Outline, Contents)
- use-https - (Outline, Contents)
- overrides - (Outline, Contents)
- fork - (Outline, Contents)
- contribute - (Outline, Contents)
- unfork - (Outline, Contents)
- policy - (Outline, Contents)
- workflows - (Outline, Contents)
- changelog - (Outline, Contents)
- canary - (Outline, Contents)
- next-version - (Outline, Contents)
- prerelease - (Outline, Contents)
Running commands
A repository fg-dist sets up — a distribution from init,
a module given its workflows by workflows — has it as a
devDependency and a dist script, so every command runs the same way:
Outline
- Sections:
- Setting up
- Keeping it current
- Deploying
- Forking a module
- The organization's policy
- Releasing a module
- Shared options
init
Scaffolds a repository.
Outline
- Sections:
- Kinds
- Options
add-module
Adds a module repository as a submodule and wires it into the distribution.
Outline
- Sections:
- What it does
- Options
extract
Turns a directory that grew inside the distribution into its own repository and a submodule of it.
Outline
- Sections:
- What it does
- Afterwards
- The tag it leaves
- Options
- A note on signing
sync
Reports where each module stands.
Outline
- Sections:
- What it also checks
- Where versions come from
- Options
bump
Moves each module to its newest version.
Outline
- Sections:
- What it touches
- Forks
- Safety
check
Fails when the distribution ships anything older than the one it extends.
Outline
- Sections:
- Exit codes
- Why a separate command
inherit
Adds every module the distribution this extends ships, and this one does not.
Outline
- Sections:
- Its license
readme
Writes the module versions into the readmes, so they are visible where people actually look.
Outline
- Sections:
- Why
- Pinned at a tag, or past one
- In a module, on its own release
- How the file is edited
- Keeping it current
- In CI
verify
Fails when a file fg-dist writes no longer says what is true, and names the command that puts it right.
Outline
- Sections:
- What it checks
- In CI
- Exit codes
migrate
Migrates the databases of what is deployed from here.
Outline
- Sections:
- In the build
- Rollbacks
- Which database
- What an app declares
- Exit codes
env
What a deployment needs in its environment, from what its apps declare: a build that refuses to deploy without it and says exactly what to add, a setup that adds it through the Vercel CLI, and a rotation of the secrets it generated, with no downtime.
Outline
- Sections:
- Which deployments
- In the build
- Setting it up
- Rotating secrets
- What an app declares
use-https
Rewrites submodule urls from ssh to https, so a build host without a key can clone them.
Outline
- Sections:
- It then checks they can be cloned
- Options
overrides
Points the workspace at this distribution's own checkouts, so a module resolves its siblings from the tree rather than from the registry.
Outline
- Sections:
- The problem it solves
- When it runs
- Which dependencies this is for
fork
Checks a module out from your fork of it, keeping where it came from.
Outline
- Sections:
- What it does
- Options
contribute
Offers the change on a module's branch upstream, as a pull request.
Outline
- Sections:
- Options
unfork
Checks a forked module out from its upstream again, once upstream has everything the fork adds.
Outline
- Sections:
- Options
policy
The organization's policy: policies/, on every module's own policies/,
and on the published policy of any distribution this one extends.
Outline
- Sections:
buildtestusesetup- Exit codes
workflows
Gives every module a publishing workflow, a changelog check and verify.
Outline
- Sections:
- The distribution itself
- What it writes
- There is no token
- The canary job
- The release job
- Pinning the actions
- Holding pull requests
changelog
Checks that a pull request has its changelog line, and prints a version's notes.
Outline
- Sections:
checkholdnotes
canary
Stamps a canary version into package.json, ready to publish.
Outline
- Sections:
- The version it picks
- The count
- Doing nothing, on purpose
- In the workflow
- The version it picks
next-version
Starts the next development cycle, once the version main was working towards has been published — and deciding what the next one is, is the whole of it.
Outline
- Sections:
- It will not choose for you
- Why it runs after, not before
- What each branch gets
- Prereleases
- Both branches record their version
- What it refuses
- Options
- Until it merges
- Moving on without a pull request
- In a distribution
prerelease
Starts the next line on a branch of its own, and leaves main exactly where it is.
Outline
- Sections:
- What it is for
- The branch it cuts
- Releasing from it
- What it refuses