Separate the published tree from internal planning material - #68
Merged
Merged
Conversation
The repository is public and is read by people evaluating the project for adoption. Internal planning material - per-increment specifications, working notes, the forward roadmap, the process templates and the process checker - is not useful to that reader and crowded out the material that is: the architecture, the security model, the standards register and the decision records. It moves out of the published tree and is retained by the maintainers. What replaces it, so the public record is not weaker: - CHANGELOG.md, derived from the tags, records what each increment delivered and how it was verified. - docs/03-conventions.md gains the engineering rules and the rules of evidence that governed every change, written as project standards rather than as instructions to a contributor. - README.md gains an assurance posture section stating the properties the build enforces - memory safety, compiled architectural boundaries, least privilege for effects, a signed receipt chain, untrusted-content handling, the FIPS leg, supply-chain audits, DCO provenance and the claim discipline of the standards register - each naming what enforces it. The gate keeps every check that applies to published code and drops only the internal process check. Three tests asserting the shape of an internal document move with it; the gate alias test now asserts the release check instead. Signed-off-by: Ayla Croft <aylacroft@proton.me>
…ndency advisory Two gaps against the OpenSSF Best Practices passing criteria, which the Linux Foundation requires at its Incubation stage: - SECURITY.md published a reporting address but no timeframe. It now states a 14-day acknowledgement target, says plainly that a single maintainer makes it a target rather than a commitment, and asks for coordinated disclosure. - The one open advisory is recorded rather than left implicit. GHSA-wrw7-89jp-8q8g against glib 0.18.5 is transitive through the GTK 0.18 stack Tauri 2.11.5 requires on Linux, so it is fixed by a Tauri release built on gtk-rs 0.20 and not by a direct bump. Its scope is stated and checkable: the headless release is steps: [:assemble] with no Burrito and no src-tauri, so a server deployment does not ship the dependency at all. The row carries an owner and the condition that lifts it. Signed-off-by: Ayla Croft <aylacroft@proton.me>
The FIPS image tag is a hash of the files that define the image, so any change to them - including a comment - names an image that must be built before it can be pulled. The fips job takes that image as its container, which GitHub pulls before the job's first step, so the job cannot retry the pull itself: it fails with 'manifest unknown' and no output. The fips-image workflow builds on the same event, so the two race and this job always loses, producing a red check on a pull request for a change that is correct. fips-tag, which already gates the fips job, now waits for the manifest to appear, polling for up to 30 minutes. The image is a function of its inputs, so the image it waits for is exactly the one the commit needs. A timeout fails with the reason and where to look, because 'still building' and 'will never exist' need different responses from the person reading it. Signed-off-by: Ayla Croft <aylacroft@proton.me>
Scorecard measures the repository against the OpenSSF's own checks - branch protection, pinned dependencies, dangerous workflow patterns, token permissions, signed releases, maintenance - and publishes the result, so that someone evaluating this project can read its posture without being asked to trust a claim made in the README. It runs weekly and on pushes to main, and uploads to the code-scanning dashboard so a regression appears beside code findings. test/workflows_test.exs restores a property that left with the internal process checker and adds one. Every workflow and the Dependabot configuration must parse as YAML, because GitHub reports a malformed workflow on its own page rather than on the pull request, which is the wrong place to discover it. And every third-party action must be pinned to a full commit hash rather than a tag, since a tag can be moved to point at different code after it was reviewed; that is Scorecard's Pinned-Dependencies check, held here rather than waited for. The population is git ls-files .github, so a workflow added without either property is caught by its own existence. Signed-off-by: Ayla Croft <aylacroft@proton.me>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The repository is public and is read by people evaluating the project for adoption. This change
separates what those readers need from what is internal to building it.
What moved out of the published tree
Per-increment specifications and working notes (159 files), the forward roadmap, the process
templates, the internal process document and the process checker. They were the largest non-code
directory in the repository and described how the work is organised rather than what the software
is or what it guarantees. They are retained by the maintainers.
What replaces them, so the public record is not weaker
CHANGELOG.md, derived from the tags rather than written from memory, recording what eachincrement delivered and how it was verified.
docs/03-conventions.mdgains two sections lifted from the internal contract and rewrittenas project standards: the engineering rules (modularity behind behaviours, compiled architectural
boundaries, OTP supervision, no runtime evaluation of model output, pinned dependency versions,
tests that do not reach the network) and the rules of evidence (a failing test before the fix,
populations derived by command, verification naming its exit code, records appended not
rewritten, deferrals carrying an owner and a lift condition).
README.mdgains an assurance posture table stating the properties the build enforces andwhat enforces each: memory safety by language choice, architectural integrity by a compile-time
boundary check, least privilege for effects through the permission gate and the separation of
identity from authority, auditability through an Ed25519 signed receipt chain, untrusted-content
handling at the boundary, approved cryptography measured on a FIPS-mode CI leg, supply-chain and
licence audits on every commit, DCO provenance enforced twice, and the standards register's rule
that no public claim is made without a row and an evidence path.
Verification
mix gateexits 0: formatting, compile with warnings as errors, boundary check, release buildcheck, Credo strict, Sobelow, dependency and licence audits, 561 tests, coverage floor.
The gate keeps every check that applies to published code and drops only the internal process
check. Three tests asserting the shape of an internal document moved with it. The gate alias test
previously asserted that the process checker was the final step; it now asserts the release check
is present exactly once, which is the property that actually protects the build.