Skip to content

Rebuild the README as an adoption surface and stop pinning claim text to it #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0j0bit wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Rebuild the README as an adoption surface and stop pinning claim text to it #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
628 changes: 290 additions & 338 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions governance/RELEASE_GATE_V1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,9 @@ NOT claimed: anyone outside this project has reviewed them
NOT claimed: the specifications are free of defects a fresh reader would find
```

Those four lines appear in `README.md`, `ICS.md`, `V1_SCOPE.md` §5.9 and the
release manifest, in the same words, so a reader cannot find a weaker version by
looking somewhere else. `check-publication-readiness.sh` fails if any of them
Those four lines appear in `ICS.md`, `V1_SCOPE.md` §5.9 and the release
manifest, in the same words, so a reader cannot find a weaker version by looking
somewhere else. `check-publication-readiness.sh` fails if any of them
loses the statement.

The clean-room implementation is independent *of the reference code* — no shared
Expand Down
6 changes: 3 additions & 3 deletions governance/V1_SCOPE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -692,9 +692,9 @@ Stable v1.0.0 tag; later implementation reports may be tracked as v1.1 errata.

One thing: an implementation built by someone else, interoperating. When that
happens it is recorded as evidence and the claim widens. Until then the release
says so in `ICS.md`, in `mcl-core/README.md`, and in the release manifest — in
the same words, so a reader cannot find a weaker version of the statement by
looking somewhere else.
says so in `ICS.md`, in this section, and in the release manifest — in the same
words, so a reader cannot find a weaker version of the statement by looking
somewhere else.

### 5.10 The builder-interoperability floor

Expand Down
4 changes: 2 additions & 2 deletions releases/v1.0.0/SHA256SUMS.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
98f7edfdb87642f0970f8052d80391188d6d9a6e146e8c9f0636f04c2563adaa *mcl-core/governance/PUBLISHING.md
207eed90edb52ea1b81bafdae5a7c9e7a0a319a63939dd821888e54fb8fb4ec0 *mcl-core/LICENSING.md
b2ed5e4adcaa336400cc8cb9c2ee18358682a26a58ca0ff012ed3f637ea8d40f *mcl-core/CONTRIBUTING.md
dfe844e21b6db6673139254355a9ec3c41e2f412a4df1a79578b046ef45b3deb *mcl-core/governance/V1_SCOPE.md
413e26e48b5bfa2fce9a2c587b4c7969fb3a2d443a389dc87d60547c54401624 *mcl-core/governance/RELEASE_GATE_V1.md
331144bea72ed2058cec7e88e3142b43b595983edad147bdb817f12ca8a82f71 *mcl-core/governance/V1_SCOPE.md
6ecd0fbc51e22d54a3ffb780b272c2e42d3fb2ecbe5461a3df8c90e9c46ec073 *mcl-core/governance/RELEASE_GATE_V1.md
24e4369b13bf3b2c635f352cf2fb4ee7dd0270dfe6e475b12feb8ca680d70897 *mcl-core/governance/GOVERNANCE.md
696369d8bc76c3f1b00f3e66622f0e5b404641e008fde80c9bad8635413e0ee2 *mcl-core/governance/ARCHITECTURE_CHARTER.md
3cf85cb41a1efe1e7c75c65a420653cdb0bad0a10324b368604e26db3163b396 *mcl-core/governance/REGISTRY_POLICY.md
Expand Down
6 changes: 3 additions & 3 deletions releases/v1.0.0/manifest.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ WHAT THIS RELEASE CONTAINS

WHAT THIS RELEASE DOES NOT CLAIM

Stated here in the same words as mcl-core/README.md,
conformance/ICS.md and governance/V1_SCOPE.md section 5.9, so that
a reader cannot find a weaker version by looking somewhere else.
Stated here in the same words as conformance/ICS.md and
governance/V1_SCOPE.md section 5.9, so that a reader cannot find
a weaker version by looking somewhere else.

NOT claimed: two ORGANISATIONS have interoperated
NOT claimed: anyone outside this project has implemented these
Expand Down
6 changes: 3 additions & 3 deletions tools/build-release-bundle.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -485,9 +485,9 @@ printf 'mcl-core/releases/%s/REPRODUCIBILITY.md
echo
echo "WHAT THIS RELEASE DOES NOT CLAIM"
echo
echo " Stated here in the same words as mcl-core/README.md,"
echo " conformance/ICS.md and governance/V1_SCOPE.md section 5.9, so that"
echo " a reader cannot find a weaker version by looking somewhere else."
echo " Stated here in the same words as conformance/ICS.md and"
echo " governance/V1_SCOPE.md section 5.9, so that a reader cannot find"
echo " a weaker version by looking somewhere else."
echo
echo " NOT claimed: two ORGANISATIONS have interoperated"
echo " NOT claimed: anyone outside this project has implemented these"
Expand Down
7 changes: 5 additions & 2 deletions tools/check-publication-readiness.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,9 +143,12 @@ else
fi

# ----------------------------------------------- 6. the claim boundary is said
#
# The claim boundary lives in the normative and release authorities. README.md
# is the adoption surface and is deliberately not required to carry it.
echo
echo "-- the release states what it does NOT claim, in every place a reader looks"
for f in "mcl-core/README.md" "mcl-core/conformance/ICS.md" \
echo "-- the normative release authorities preserve the claim boundary"
for f in "mcl-core/conformance/ICS.md" \
"mcl-core/governance/V1_SCOPE.md" \
"mcl-core/releases/v1.0.0/manifest.txt"; do
if grep -q "NOT claim" "$ROOT/$f" 2>/dev/null; then
Expand Down
Loading