Cut 0.1.0 release

[DavidCozens]

Release checklist for the first stable tag.

Route: curated 0.1.0, release-please takes over at 0.2.0

Decided 2026-08-17. This issue previously described release-please cutting
0.1.0 itself, which contradicted the unpark steps in
.github/workflows/release-please.yml and could not work: seeding
.release-please-manifest.json to 0.1.0 tells release-please that 0.1.0 has
already shipped, so its next pull request would propose 0.2.0. The two are now
reconciled in favour of the workflow's version.

Why, with the numbers. The parked comment says a generated changelog over all
of main would overflow GitHub's pull-request body limit. Measured on 2026-08-17:
426 entries across the six configured sections — 169 feat, 92 docs, 51
refactor, 47 ci, 42 chore, 25 fix — plus a breaking-changes block from 9
! commits. At roughly 150 characters an entry that is about 64,000 characters
against a 65,536 limit. The parking was right by a margin of about 2%.

The curated route also gives 0.1.0 the release notes it deserves. A generated list
of 426 commits is not what someone deciding whether to adopt the library needs to
read.

Sequence

1. All other 0.1.0-milestone blockers closed — S23.22 (S23.22: final documentation and comment quality gate before 0.1.0 #708) is the last one

2. Public API freeze reviewed — Public API freeze review before 0.1.0 #652, closed 2026-07-20

3. Pre-cut documentation sweep (see below)

4. Write the 0.1.0 release notes by hand, to the shape now stated in
   docs/release-process.md (What the release notes contain). For 0.1.0
   that is parts 1 and 2 only — no generated list, because it is the first
   release and every commit since the repository began describes the library
   rather than a change to it.

   **Say so inside the entry**, in one line: this is the first release, so
   everything in it is new and there is no list of changes. That is the only
   permanent home the exception needs. `docs/release-process.md` describes the
   recurring process and deliberately does not mention 0.1.0 — nobody cuts it
   twice — and this issue closes, so the entry has to explain itself to a
   reader who meets a prose entry followed by generated ones.
   - *What's in this release* — what the library is and the deliberate scope
     (source-only, no dynamic allocation), then the compliance snapshot and
     the platform list. **Restate both; do not link the site for them.** The
     site publishes from `main`, so a link out of this release would resolve
     to a later state and lose what 0.1.0 shipped. Link
     `blob/v0.1.0/docs/rfc-compliance.md` for the full detail — the tag is
     frozen even though the site is not.
   - Compliance at 0.1.0, read off the matrix at the tag rather than from
     memory, as *Total / Supported / Partial / Not Met / N-A*:
   
     | RFC | Total | Supported | Partial | Not Met | N/A |
     |---|---|---|---|---|---|
     | RFC 5424 | 40 | 33 | 0 | 0 | 7 |
     | RFC 5425 | 20 | 13 | 1 | 1 | 5 |
     | RFC 5426 | 17 | 8 | 0 | 0 | 9 |
     | RFC 6587 | 8 | 7 | 0 | 0 | 1 |
   
   - Platforms: Posix, Windows, FreeRTOS, FreeRTOS-Plus-TCP, lwIP (Raw API),
     OpenSSL, Mbed TLS, FatFs, FreeRTOS-Plus-FAT, C11 atomics.
   - *Known limitations* — #718, #719, #731, #732, #733, #734 (TLS contract
     divergences), #736 (oversize datagram above the default message cap),
     #755 (FreeRTOS `sysUpTime` early wrap) and #753 (fingerprint
     authorisation). Frame them as found by pre-release audit and disclosed on
     the affected platform pages. `CHANGELOG.md` is not published to the site,
     so bare `#nnn` autolinks on GitHub and needs no markdown link.
   - Write once to a file: `gh release create --notes-file` for the Release,
     same text into `CHANGELOG.md`.
   

5. Seed .release-please-manifest.json to 0.1.0

6. Seed version.txt to 0.1.0. release-type: simple manages this file and
   it does not exist yet; seeding it avoids release-please introducing it as a
   surprise in the first 0.2.0 pull request. It must agree with the manifest,
   which is what sbom.yml reads the version from

7. Create the tag and GitHub Release as a draft first. release: published
   does not fire for a draft, so this is the inspection gate: check the tag,
   the notes and the source archives before anything is signed

8. Publish the draft. That fires sbom.yml, which attaches four assets

9. Verify per security/release-verification.md
   — that the bundles verify, not merely that the assets are present

10. Unpark release-please: restore on: push: branches: [main] and rewrite the
    parked comment block, which describes its own removal

11. Verify docs/ci.md:127 — "release-please runs on every push to main" is
    false while parked and becomes true here. Confirm rather than edit

Traps found during the pre-cut audit

• Never git push --tags. Local clones may carry v1.0.0 and v1.1.0 from
  the pre-history-strip template era. The remote has no tags. Publishing those
  would put 1.1.0 ahead of 0.1.0 in semver and give release-please a false
  baseline to compute from. Deleted locally 2026-08-17; recorded here because a
  fresh clone of an old backup could reintroduce them.
• "Re-run the job" means re-run the failed release-triggered run, not a fresh
  workflow_dispatch. The publish job is gated on
  github.event_name == 'release', and the cosign certificate identity binds to
  refs/tags/v<version>. A dispatched run executes from refs/heads/main, so
  publish is skipped — and were it to sign, the identity would not match the
  documented verify command.
• No documentation snapshot is produced by a release. Nothing in ci.yml
  triggers on release; the site deploys on push to main only. That is S23.05: Versioned documentation publishing and version switcher #251,
  targeted at 0.2.0. Do not expect a versioned docs directory to appear.

Pre-cut documentation sweep

Every .md file and every source comment was swept for 0.1.0 / 1.0.0 on
2026-08-05, and re-verified against the tree on 2026-08-17. Source comments are
clean: there is no release-version reference anywhere in Core/ or Platform/.

Required — these state the release does not exist

• .github/workflows/release-please.yml:3-13 — the parked comment block.
  Rewrite alongside step 10 above.
• docs/release-process.md:35-37 — delete the "> Status: release-please is
  parked …" blockquote. Public docs page, and it contradicts its own checklist
  further down.

Consequential — stale once the manifest is seeded

• docs/security/sbom.md:79 — drop the "Pre-release: 0.0.0" clause from the
  metadata.component.version row.

Settled

• CLAUDE.md:295 — "0.1.0 is the first public release…" reads as future
  tense. Left as written: it defines what the milestone means rather than claiming
  the release has not happened, it is an internal process document, and rewriting
  it on release day is churn no reader benefits from. CLAUDE.md:274 (the backfill
  record) and CLAUDE.md:289 (the due dates) stay as written — historical or still
  true.
• The cosign signing wording was carried as a judgement call to revisit at
  0.2.0. Neither phrase survives; the S23.22 audit rewrote both. Nothing to do.
• README pre-0.1.0 warning banner — removed in 555349c (docs: S23.18 replace the reference designs with an integration path, and document the Make consumer #658), from both
  README.md and docs/README.md. No copy survives anywhere in the tree.

Deliberately out of scope

• "beta stack" naming — docs/build-integration.md, the committed
  docs/generated/beta-stack-manifest.txt, and the anti-drift lane in ci.yml.
  Accurate while 0.1.0 is the beta. Renaming moves a generated file and a CI
  lane, so it belongs after the beta label stops applying.
• Every 1.0.0 in the tree is unrelated to our 1.0.0 milestone — the PolyForm
  Noncommercial licence version, its SPDX identifier, or a test fixture
  SwVersion. Do not find-and-replace.

After the tag

• Invite scrutiny of the TLS obligations. See the first comment below —
  this is the strongest action on this issue and the easiest to lose in the
  mechanics of tagging.

This issue is the release-day close-out; it should be the last to close on the
milestone.

[DavidCozens]

At publication: invite scrutiny of the TLS obligations

docs/tls.md (PR #730) states a security posture that is reasoned rather than
field-tested: a fault is reported and delivery continues, because a reporting
channel that fails closed is a way to blind the collector at the moment it
matters. Peer-identity mismatch is the single exception.

That posture is the least field-tested thing in the library, and it is cheap to
change during 0.x and expensive afterwards — once integrators depend on a stream
that keeps delivering through a bad clock, changing it is a security-relevant
behaviour change. 0.1.0 is exactly the release to settle it in.

So at publication, invite challenge from people who run these networks. Two notes
on how:

• Frame it as deliberate, not uncertain. The audience is engineers evaluating
  during procurement. "This posture is deliberate, here is the reasoning, we
  invite challenge" reads as a maintainer who has thought about it; "we are not
  sure this is right" reads as immaturity. Same request, opposite impression.
• Ask something falsifiable. "Is this the most useful contract?" gets no
  answers. "Your device's clock is three years fast because someone tampered with
  the time source, so its certificate now looks expired — keep delivering with an
  error raised, or stop?" gets answered by anyone who has run an ICS network. The
  same treatment suits the half-supplied client credential, and whether
  peer-identity mismatch really is the one case worth blocking on.

Put it somewhere replies accumulate — a discussion or an issue, linked from
tls.md — rather than only on the page, which invites reading and not replying.

[DavidCozens]

In the release notes: one planned breaking change

#735 — pulling TLS credentials and the expected peer identity on connect rather
than copying them when the stream is created — changes
SolidSyslogOpenSslStreamConfig and SolidSyslogMbedTlsStreamConfig, turning
value fields into callbacks in the shape SolidSyslogEndpointFunction already
uses. Pre-1.0 that bumps the minor rather than the major, per
docs/release-process.md.

State it in the 0.1.0 release notes. docs/tls.md already carries it for anyone
reading the documentation, but a release note reaches the integrator who is
pinning a version rather than browsing.

Be specific, and say what is not affected. "The TLS API may change" is worse
than silence — it makes an integrator defensive about all of it. Name the two
config structs and the fields, and say the Stream role, the sender wiring and
the rest of the public API are untouched, so they know what to insulate and what
to use directly.

The versioning policy is already documented; what this adds is forward notice,
which turns a surprise in 0.2.0 into a plan an integrator agreed to.

[DavidCozens]

Retracting the planned breaking change

The note above about a planned break in the TLS config structs was based on a
wrong reading, and is withdrawn. Do not put it in the release notes.

The claim was that credentials and the expected peer identity are copied when the
stream is created and cannot be changed afterwards, so closing the gap would mean
turning value fields into callbacks.

Both adapters in fact dereference the pointers they were given on every Open.
An integrator who owns the buffer or handle can replace the material and force a
reconnection, and the next connection uses it — so a device issued new
credentials while running already uses them without restarting. Nothing needs to
break to deliver that.

What remains of #735 is an optional version function so the stream can detect the
change itself, the way the destination endpoint already does. That is additive,
so there is no breaking change to announce.

Announcing a break we do not need would be worse than saying nothing: integrators
would insulate setup code against a change that is not coming.

[DavidCozens]

Changelog policy settled — #775

ci, chore and docs are now hidden in release-please-config.json, so the generated list carries feat, fix and refactor only. Breaking changes surface in their own section regardless.

Two consequences recorded on this issue:

The generated changelog is no longer near the limit. Measured across main, all six sections came to roughly 64,000 characters against GitHub's 65,536 pull-request body limit — the failure this workflow is parked for, with about 2% to spare. With three hidden it is about 37,000. Route B is still the right call for 0.1.0 on the strength of the curated notes alone, but the overflow risk is now gone as a standing concern for 0.2.0 onward too.

Hiding docs moved a responsibility onto the release notes. A documentation change that corrects a claim an integrator could have acted on no longer appears anywhere automatically — #769 and #772 are both this week's examples. docs/release-process.md now states that the prose section carries it. Worth remembering when writing the 0.1.0 notes: the S23.22 audit corrected a number of claims, and any that an integrator could have designed around belong in part 1.

refactor was left visible. It fails the same consumer-impact test on principle, and hiding it is a one-line change if that is preferred before #775 merges.

[DavidCozens]

Released. v0.1.0 is tagged at 90b9ef9, published, and verified.

Every checklist item is done. What actually happened, where it differed from the
plan, and what it turned up.

The route

Cut by hand, not by release-please, per the reconciliation recorded on this issue.
The reason was measured rather than assumed: a generated changelog over all of
main came to 426 entries and roughly 64,000 characters against GitHub's 65,536
pull-request body limit. The parking decision was right by about 2%.

#776 seeded the baseline - manifest and version.txt to 0.1.0, the
hand-written changelog entry, and the Pre-release: 0.0.0 clause off the SBOM
field table. #777 unparked release-please and removed the two places that said
the release had not happened.

What shipped

Tag	refs/tags/v0.1.0 at 90b9ef9, created by gh release create --target
Release	Published 2026-08-18, not a draft, not a prerelease
Assets	sbom.cdx.json, source-tree-sha256.txt, and a cosign bundle for each
SBOM	metadata.component.version 0.1.0, purl pinned to 90b9ef9
Content-tree hash	a10bbe54f8e9cf981a94032f4b309a82861bd10456816c00496dcf4f3dbbc564
Signatures	Both verify under cosign v3

The content-tree hash is byte-identical to the value computed locally before the
release. Worth recording why: the product scope is Core/ + Platform/ plus the
build and licence files, so none of the documentation work between the dry run and
the tag moved it. The scope behaves as designed.

The draft step was dropped

Step 7 originally said to create the Release as a draft and inspect the tag first.
That was wrong on its own terms: GitHub does not create the git ref for a draft, so
there is no tag to inspect until publication. The draft would have checked the
prose and the target commit only, since nothing is signed or attached until the
release: published event fires. It was dropped rather than reworded.

What verification turned up

Running the documented procedure against the published assets, rather than reading
it, found a defect in docs/security/release-verification.md. It asked for cosign
v2 or later. Signatures are produced by cosign v3, which writes the current
Sigstore bundle format; v2 cannot read it and fails with bundle does not contain cert for verification - an error that reads as a broken signature rather than a
version mismatch.

That sat on the first command a security-conscious evaluator runs, on the first
release. Fixed in #777. The v0.1.0 tag keeps the wrong text, which is
unavoidable, but the site publishes from main so the published guide corrected on
merge.

Also cleared

• chore(main): release 0.1.0 #101, a release pull request opened 2026-04-11 and left open, whose tip
  commit was not on main's history after the rewrite. Against main it proposed
  moving the manifest to a value it already held and would have overwritten the
  0.1.0 changelog entry with a four-month-old generated one. Closed, and its
  branch deleted so the 0.2.0 release pull request starts clean on the name
  release-please reuses.
• Two stale local tags, v1.0.0 and v1.1.0, from the pre-history-strip
  template era. The remote had no tags; pushing those would have put 1.1.0 ahead
  of 0.1.0 in semver and given release-please a false baseline.
• docs/ci.md's statement that release-please runs on every push to main,
  which was false while parked and became true on unpark. Confirmed rather than
  edited.

Release-please is live

Its first push-triggered run succeeded - the two historical ones failed, which was
the parking reason - and correctly opened nothing, the only commit since the tag
being a chore. The first release pull request it does open is also the live check
that the hidden changelog sections took effect: it should carry feat and fix
only.

Carried forward

Inviting scrutiny of the TLS report-and-continue posture is now #778. It is the
one item from this issue that is not release mechanics, it needs an audience to
reach, and it is better raised alongside an announcement than as a same-hour
afterthought. The release notes carry one sentence of it.