Make the README a front door instead of a specification cover page - #2
Conversation
Anyone arriving here got "Scope" and "Non-goals" and no way to tell whether
this repository was the one they needed, what MCL would look like in their own
code, or where to go if it was not. That is the right shape for a reader who
already knows what MCL is, and the wrong shape for everyone else.
The specification content is unchanged and still here, underneath. What is new
sits above it:
- the OJOBIT banner, and badges that carry live state -- CI status is the
real workflow badge, so it goes red on its own rather than being a
decoration
- one sentence saying what this repository is for, in plain language
- a routing block. Most people should not read a specification to use MCL,
they should use mcl-sdk, and the README now says so at the top instead of
letting them find out later
- a short "why this exists" that gives the reason the layer is shaped this
way, rather than restating the scope list immediately below it
Maturity is stated on the badge rather than buried: which profiles are Stable,
which are Candidate, and -- for mcl-uwb -- that the binding is specified but has
never been run on hardware, with a pointer to the bindings that have. A reader
deciding what to build on should not have to dig for that.
No specification text, normative wording, conformance claim or evidence
reference was altered, and no executable source is touched.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Closed without merging: post-release adoption work, not release closure. Branch |
|
Correction to the close comment above: this is NOT post-v1 work. The adoption-facing front doors were explicitly requested by the owner and are PRE-Candidate — if the goal is maximum adoption at first publication, they belong in the tree before the Public Candidate freeze. What was wrong was sequencing, not scope: this was opened while the first public Linux CI run had just exposed a real evidence-integrity defect, and release-integrity fixes come first. This branch is preserved deliberately. It will be rebased onto the new main (the base moves once the digest fixes land), have CI rerun, and be reopened for review before the freeze. It is parked, not abandoned. |
main moved when the release-integrity fixes and the rows 27/37 closure merged. Merged rather than rebased so the preserved branch history is kept and no force-push is needed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every claim here was checked before it was written, and three were wrong. - mcl-sdk said to clone it alone and build. A fresh anonymous clone fails to configure, because the repository builds against its sibling specifications. The README now gives both real paths, each verified from anonymous downloads: the release developer SDK archive, one CMake project with no sibling checkout, and the eight repositories cloned side by side. Both configure, build and run the Base 1 example to CONTACT_ESTABLISHED on both sides. - The mcl-sdk snippet passed a string where mcl_machine_config_deployment takes a numeric source reference and a role, and admitted on PEER_DETECTED where the API raises POLICY_REQUIRED. The replacement was compiled with -std=c99 -Wall -Werror against the real headers, linked and run: init and start return MCL_MACHINE_OK with only clock_ms, transport_send and user set, which is what the prose now says Base 1 needs. - mcl-uwb carried a status badge the ICS does not use. The ICS says experimental, so the badge does. Also: the SDK-first callouts no longer call the mcl-sdk repository one CMake project with no sibling checkout, which describes the release developer SDK; mcl-link no longer sets the 104-migration campaign, which carried major-0 traffic, directly beside the Link major 1 Stable claim; the organization profile no longer calls the specifications frozen before the Candidate is sealed. CODEOWNERS prose: @0j0bit and @sed-boi are two accounts controlled by the same project owner. That is account redundancy, not independent two-person review. Owner patterns are unchanged. No specification text, conformance claim, evidence reference or executable source changed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…pository check-provenance.sh refuses a binary outside the accounted evidence and experiment locations, and it was right to: eight copies of a brand image in eight release repositories is eight unaccounted binaries, and eight places for one asset to drift. The banner now lives once, in the .github organization-infrastructure repository, and each README references it there. No gate was loosened to make this pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Reopened after release closure. The release-integrity fixes (mcl-ap #1, mcl-core #1) and the rows 27/37 closure (mcl-core #3) are merged, and public CI plus This branch was preserved, brought up to date with
Scope: only README, banner and CODEOWNERS prose. No specification text, conformance claim, evidence reference or executable source is changed. The local exact-head rehearsal passes with every repository on its adoption branch. |
0j0bit
left a comment
0j0bit
left a comment
There was a problem hiding this comment.
Reviewed as 0j0bit: presentation scope only (README.md); facts verified before merge (build paths run from anonymous downloads, snippet compiled/linked/run against the real headers, badges checked against ICS); CODEOWNERS prose states the two accounts are one owner. Local exact-head rehearsal 22/22 with every repository on its adoption branch.
1 participant
Make the README a front door instead of a specification cover page
Anyone arriving here got "Scope" and "Non-goals" and no way to tell whether
this repository was the one they needed, what MCL would look like in their own
code, or where to go if it was not. That is the right shape for a reader who
already knows what MCL is, and the wrong shape for everyone else.
The specification content is unchanged and still here, underneath. What is new
sits above it:
real workflow badge, so it goes red on its own rather than being a
decoration
they should use mcl-sdk, and the README now says so at the top instead of
letting them find out later
way, rather than restating the scope list immediately below it
Maturity is stated on the badge rather than buried: which profiles are Stable,
which are Candidate, and -- for mcl-uwb -- that the binding is specified but has
never been run on hardware, with a pointer to the bindings that have. A reader
deciding what to build on should not have to dig for that.
No specification text, normative wording, conformance claim or evidence
reference was altered, and no executable source is touched.
Co-Authored-By: Claude Opus 5 noreply@anthropic.com