Jorijn van der Graaf
54aaf078b2
The README offered master builds as the `beta` branch, AGENTS.template.md described the `latest` tag CI force-pushed, a release as a tag pushed after master, and CI as running on every push to master, and the repo-better-solution lens told reviewers that users get master through `beta`. The README now says that releases go to `stable`, the branch its install commands pick even while the repo still holds the old `beta` branch. AGENTS.template.md says that every pushed range adds a release entry and goes out in one push with a signed tag on the commit master receives, its last commit or, on the pull-request path, the merge, how to write the entry, what every run checks before building and what a tag run also checks, publishes and creates, what follows when one fails, what CI runs for, and what becomes of `beta`; the lens says users get master through releases on `stable`. The entry's rules are the owner's: at most three sections, New, Fixes and Breaking, the most important item first and nothing after them, and a version that is a major for a Breaking section, a minor for New items and a patch for Fixes alone. The release paragraph also gets the blank line that keeps it apart from the one on local builds.
42 lines
2.4 KiB
Markdown
42 lines
2.4 KiB
Markdown
## This repository: Crafter.Build
|
|
|
|
A C++26 modules build system that builds itself. The stated design is
|
|
`README.md` (the manual) and `AGENTS.template.md` (the contributor guide;
|
|
`AGENTS.md` is written from it by a crafter-build build or test run, not
|
|
by `build.sh`, and is not in the tree).
|
|
Its "Design rules" and "Security considerations" are the owner's
|
|
decisions: a range that departs from one without saying so is a finding;
|
|
whether one should change is the owner's call, not a defect of the range.
|
|
Among them, for CI, which holds the workflow's token and the signing key
|
|
its runner mounts: no secret is added to the workflow, and the
|
|
environment is never echoed in it.
|
|
|
|
The layers: the library (`interfaces/`, `implementations/`), which the
|
|
executable wraps and every `project.cpp` is compiled against; this
|
|
repository's own `project.cpp`; `build.sh`, the bootstrap that builds the
|
|
tool without the tool; the Flatpak (`packaging/flatpak/`), which bundles
|
|
the LLVM users build with; CI (`.forgejo/workflows/ci.yaml`). A target
|
|
difference branches on `cfg.target` at run time, never on the host; an
|
|
output path goes through `BinDir()`, `BuildDir()` or `PcmDir()`; whatever
|
|
changes what gets compiled or bundled reaches `VariantId()`.
|
|
|
|
Search first: the partitions' own helpers (`RunBuildCommand`,
|
|
`RunCommandChecked`, `Progress::Diagnostic`, `ApplyStandardArgs`,
|
|
`HostTarget`, `GitProject`, `LocalProject`); the Crafter.* libraries the
|
|
tree already uses, cloned under `~/.cache/crafter.build/external/`; libc++
|
|
and clang as the host installs them (`/run/host/usr/include/c++/v1`,
|
|
`/run/host/usr/lib/clang/`); git, cmake and flatpak-builder.
|
|
|
|
Commit shape here: a fix, its test and its README change are separate
|
|
commits when each stands on its own, in that order, and a bug fix ships
|
|
with a test that fails before it. That split is not a later commit
|
|
repairing an earlier one.
|
|
|
|
Compatibility: the `project.cpp` of every sibling repository beside this
|
|
checkout (`../Crafter.*/project.cpp`) and of every user compiles against
|
|
what `interfaces/` exports and is loaded by the binary; the CLI, the
|
|
`CRAFTER_BUILD_*` variables, the cache an older version left under
|
|
`~/.cache/crafter.build/` and the `bin/` layout CI globs are contracts too.
|
|
Users get master through releases on the Flatpak's `stable` branch. A
|
|
change an existing `project.cpp` does not survive is a
|
|
finding unless the range documents, in the README, what users must change.
|