Introduction

Public Software is a from-scratch, spec-first reimplementation of the software world as one suite: firmware, kernel, toolchain, desktop, office, media, engineering, enterprise. It is written in Rust and held in public.

Every repository in the organization signs the same contracts, so the parts fit together. Nothing here is a fork of an existing project; where a standard exists, the suite implements the standard, and where a standard is paywalled or closed, the specs repository keeps a living, executable one.

What this handbook is

This is the reference for how the suite is organized and how it is built. It is generated from the same catalog that configures the GitHub organization, so what it says about repositories, rings, layers and waves is what the organization actually enforces.

• The suite lists every repository, what it is for, which layers of the stack it serves, and when it becomes buildable.
• How we work states the contracts: spec-first cleanroom, RFCs, sign-off, licensing, the release train.
• Contributing is the short path from a first issue to a merged change.
• Glossary defines the terms the catalog uses.

Status

The organization was bootstrapped on 2026-09-02. Every repository exists with its skeleton, its team, its rulesets and its labels. The first release train is 2027.1. No crate has shipped yet; the handbook will say so, per repository, until one does.

The suite

Every repository in the organization, by dependency ring. Generated from the catalog.

Spine

Defines, assembles and documents everything else.

Platform

The crates every repository uses.

System

Toolchain, silicon, kernel, base, infrastructure, media, shells.

Domain

The products.

Standards

Living specs and open data.

How we work

Spec-first, cleanroom

A component starts from a specification, not from another implementation. Where a public standard exists, the suite implements it and runs its conformance suite. Where the standard is closed or paywalled, the specs repository keeps a living specification and an executable conformance suite, and the implementation targets that. Provenance is recorded per repository in PROVENANCE.md: what was consulted, and what was deliberately not.

Rings and layers

Every repository sits in one dependency ring, and dependencies may only point inward:

Layers L0 to L18 are the ledger: the rungs of the stack from silicon to content. A repository declares the layers it serves; the organization records them as a custom property on the repository.

Waves

A wave is when a repository’s first crate becomes buildable. Wave 1 is the spine and the platform; later waves follow the dependency rings outward. The public Roadmap project mirrors the catalog’s waves, layers, readiness and rings as fields.

Changes that cross a repository

Anything that changes an interface or touches more than one repository goes through an RFC in the rfcs repository: a template, a comment window, a decision log. Interfaces are WIT packages and wire schemas in interfaces; binding crates are generated from them.

Sign-off and licensing

Every commit carries a Developer Certificate of Origin sign-off (git commit -s); the organization enforces it. Code is licensed Apache-2.0 OR MIT; content and specifications are CC-BY-4.0.

Branches, reviews, releases

• main takes changes by pull request, with one approving review, code-owner review, resolved threads, signed commits and a linear history. Platform-ring repositories require two reviews.
• Release branches are release/**; release tags are immutable.
• The suite repository pins every crate in one lockfile and builds the whole suite nightly. Release trains are named by year and number; the first is 2027.1.

Where the code lives

GitHub is a mirror. The canonical home of the organization will be its own forge, built in the forge repository; until then, every repository mirrors to it automatically once the mirror is stood up.

Contributing

Find something to do

Every repository labels beginner-friendly work good first issue. The organization-wide search is the fastest way in: open good first issues across the organization.

Design questions that cross repositories are RFCs: open RFCs.

Set up

cargo install pub
pub suite pull        # every repository, at the pinned revisions
pub check             # the conventions every repository must pass

Rust 1.90 or newer, edition 2024.

Make the change

1. Open an issue, or pick one. If the change touches an interface or more than one repository, open an RFC first.
2. Branch from main. Keep the change to one concern.
3. Sign every commit off: git commit -s. Sign it too; main requires signed commits.
4. pub check must pass. So must the repository’s CI.
5. Open a pull request. One approving review from a code owner merges it; platform-ring repositories need two.

Provenance

If you consulted an existing implementation while working, say so in the pull request. PROVENANCE.md in each repository records what may and may not be consulted for that component; the kind/provenance label is for questions about it.

Conduct and security

The code of conduct applies everywhere in the organization. Security reports go to hello@publicsoftware.dev or through private vulnerability reporting on the repository; see the security policy.

Glossary

Catalog. The machine-readable ledger of every repository: purpose, ring, layers, wave, contents. It lives in the catalog repository and is the source of truth for GitHub descriptions, topics, custom properties, the organization README and this handbook.

Ring. A repository’s dependency tier: spine, platform, system, domain or standards. Dependencies point inward only. Each ring has a colour in the identity.

Layer. A rung of the stack, L0 (silicon) to L18 (content). A repository serves one or more layers; all means the whole ledger.

Wave. The roadmap phase in which a repository’s first crate becomes buildable, 1 to 5.

Readiness. How far a repository’s flagship component has come: shipped, partial, seed or none.

Tier. The review tier of a repository: incubating, stable, core or archived.

Release train. A coordinated release of the whole suite, named by year and number, for example 2027.1. The suite repository’s lockfile pins it.

Spec-first cleanroom. Implementing from a specification and its conformance suite rather than from another implementation, with provenance recorded.

RFC. A design proposal that crosses repositories or changes an interface; lives in the rfcs repository with a decision log.

DCO. Developer Certificate of Origin; the Signed-off-by line every commit carries.

WIT. The WebAssembly Interface Types language, used in interfaces to define every cross-repository API as public:<area>/<interface>@x.y.z packages.

pub. The organization’s command-line tool: scaffolds repositories, checks conventions, syncs the catalog to GitHub, pulls and builds the suite.