Overview
- What a distribution is - (Outline, Contents)
- Versioning - (Outline, Contents)
- Modules - (Outline, Contents)
- Extending - (Outline, Contents)
- Policies - (Outline, Contents)
- Deploying - (Outline, Contents)
- Changelogs - (Outline, Contents)
- Forking a module - (Outline, Contents)
- Running a distribution - (Outline, Contents)
- Releasing a module - (Outline, Contents)
- Growing a module in place - (Outline, Contents)
- Submodule urls - (Outline, Contents)
What a distribution is
A distribution is a repository that ships a set of modules together.
Outline
- Sections:
- The shape
- What the manifest holds
- What each piece does
Versioning
Two audiences want different things from a version number, so a distribution gives them different ones.
Outline
- Sections:
- Months for end users
- Semver for developers
- Where a version comes from
- Published distributions
- Maintenance branches
- Yearly
- Quarterly
- Modules do not get LTS
Modules
A distribution is apps and the packages they share.
Outline
- Sections:
- Apps and packages
- How they resolve
- Two workspaces, one module
- Install from the root
- Build scripts
- Modules that are not JavaScript
- Public and private
Extending
A distribution may extend another.
Outline
- Sections:
- Starting one
- The floor
- What enforces it
- Publishing a distribution
- Forks
- What it is for
Policies
A distribution is run by an organization, and the organization has rules: who may join, who may see what, what it takes to approve something.
Outline
- Sections:
- Where they live
- Versioned with the distribution
- Built once, run everywhere
- Starting one
Deploying
A distribution made only of Next apps can serve them from one deployment.
Outline
- Sections:
- One deployment
- Separate deployments
- Databases
- Environment
- Which app composes the others
- Consequences for the floor
Changelogs
A release's notes are written before it is released: every change adds its own line as it merges, so when the version goes out there is nothing left to write.
Outline
- Sections:
- A module's
- Between a release and the next version
- A distribution's
Forking a module
A distribution can fix a module it ships without waiting for upstream: fork the module, ship the fix, offer it upstream, and go back to upstream once it has the fix — or keep the fork.
Outline
- Sections:
- What a fork is
- Pins outlive pull requests
- Keeping up
- Going back
- In the changelog
- In an extension
Running a distribution
dev serves the monolith, and modular:dev runs each app on its own hostname.
Outline
- Sections:
- With a monolith
- Every app on its own
- Stable hostnames instead of ports
- Documentation
Releasing a module
A distribution is versioned by month, because what it means to a user is when.
Outline
- Sections:
- What the version promises
- Stable and iterative libraries
- Main carries the next version
- Starting the next line early
- Maintenance branches
- Dist-tags
- Recording it in the source
- Versioned documentation
- The flow, end to end
Growing a module in place
A new app or package is easier to get working inside the distribution, where the workspace already resolves it and there is one repository to run.
Outline
- Sections:
- What happens
- Afterwards
Submodule urls
.gitmodules is committed, so whatever url is recorded in it is what every
later clone uses — including a build host that has no SSH key.
Outline
- Sections:
- Rewriting
- Fixing an existing repository
- Https is not enough