From da3cb31ef1976fcb8681e9d5a45acac2e242a11d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 05:29:02 +0000 Subject: [PATCH 1/4] chore(release): map breaking changes to major again now that 1.3.0 is out The override that mapped a breaking commit to a minor release existed for the window before 1.3.0, so that the API corrections in it could not publish 2.0.0. That window closed with the v1.3.0 tag, and eng/verify-release-config.mjs has required the major mapping since 1.3.0 entered the changelog: every pull request would otherwise fail its "validate release config" job. Checked by putting minor back: the script exits 1 and names this file. With major it passes. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01UWRpkQzKkNDYz3WiNgWvWU --- .releaserc.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.releaserc.json b/.releaserc.json index 5544cee6..ea5f06dc 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -5,7 +5,7 @@ ["@semantic-release/commit-analyzer", { "preset": "conventionalcommits", "releaseRules": [ - { "breaking": true, "release": "minor" }, + { "breaking": true, "release": "major" }, { "type": "feat", "release": "minor" }, { "type": "fix", "release": "patch" }, { "type": "perf", "release": "patch" }, From 778e4d988e89411cfed5d0e4d3c62d7418d9fbd9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 05:29:02 +0000 Subject: [PATCH 2/4] docs: describe 1.3.0 as released, and record how it came about The texts written for the time before 1.3.0 said there was nothing to install, that the public surface could still change, and that a breaking change bumped the minor. None of that is true after the release. - The nine package READMEs, the root README, the website start page and the packages overview now say that 1.3.0 is the first stable release, that 1.0.0 to 1.2.3 are unlisted and deprecated and should not be used, and that SemVer holds from here on. The warning that there was nothing to install is gone. - The Uds README's list of types that could still change is gone with the window it belonged to. - docs/release-process.md and CLAUDE.md describe the major mapping instead of the temporary minor one, and the dry-run note now says what a dry run does when no release is pending instead of saying it cannot succeed before 1.3.0. - The arc42 constraint and a comment in GitVersion.yml are put in the past tense. - ADR 0001 keeps its text as decided and gains an Outcome section: what the checklist ended up as, the three further API changes made on the way, and the dry-run failure that was found and fixed before the release. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01UWRpkQzKkNDYz3WiNgWvWU --- CLAUDE.md | 10 +++--- GitVersion.yml | 12 +++---- README.md | 13 +++---- docs/architecture/arc42-CanKit.Pro.md | 2 +- .../0001-versioning-and-api-stability.md | 36 +++++++++++++++++-- docs/index.md | 6 ---- docs/packages/index.md | 13 ++----- docs/release-process.md | 29 +++++++-------- src/CanKit.Pro.Actor/README.md | 9 +++-- src/CanKit.Pro.Addressing/README.md | 9 +++-- src/CanKit.Pro.CANopen/README.md | 8 ++--- src/CanKit.Pro.IsoTp/README.md | 8 ++--- src/CanKit.Pro.J1939/README.md | 8 ++--- src/CanKit.Pro.J1939Tp/README.md | 9 +++-- src/CanKit.Pro.RawCan/README.md | 9 +++-- src/CanKit.Pro.Reliability/README.md | 9 +++-- src/CanKit.Pro.Uds/README.md | 9 ++--- 17 files changed, 99 insertions(+), 100 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2e84ad6f..e0f5a616 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -239,10 +239,12 @@ say so. Twice in one wave that phrasing turned an obvious fix into a wait. ## Versioning -Until the `v1.3.0` tag, `docs/decisions/0001-versioning-and-api-stability.md` governs: breaking -changes are allowed, they map to a **minor** bump, and no `[Obsolete]` shim is introduced to dodge -one. `eng/verify-release-config.mjs` enforces both ends of that and fails the build if the rule -and the changelog disagree. +1.3.0 is out (`v1.3.0`), so the window that `docs/decisions/0001-versioning-and-api-stability.md` +describes is closed and SemVer holds. A breaking change needs the `!` and a `BREAKING CHANGE:` footer in +the commit message and publishes a **major** version: `.releaserc.json` maps `breaking` to `major`, and +`eng/verify-release-config.mjs` fails the build if it maps to anything else. A deprecation is an +`[Obsolete]` member that a later major removes. The decision record stays as the account of how 1.3.0 +came about. ## Upstream diff --git a/GitVersion.yml b/GitVersion.yml index 952c0981..28ab2a60 100644 --- a/GitVersion.yml +++ b/GitVersion.yml @@ -72,12 +72,12 @@ branches: # artifact list reads exactly like one. With the label it is `1.2.4-ci.12` and says so, which # is the whole of what this needs to fix. # - # Increment stays Patch. Raising it to Minor while the work heads for 1.3.0 would name CI - # artifacts after the version they are heading for -- but `increment` is unconditional, so it - # would go on producing 1.4.0-ci.N after 1.3.0 ships instead of 1.3.1-ci.N, and nothing would - # restore it. One temporary override with a machine-enforced expiry (breaking -> minor, in - # .releaserc.json) is a debt worth carrying; a second one, for nothing but the cosmetics of an - # artifact name, is not. + # Increment stays Patch. Raising it to Minor while the work headed for 1.3.0 would have named CI + # artifacts after the version they were heading for -- but `increment` is unconditional, so it + # would have gone on producing 1.4.0-ci.N after 1.3.0 shipped instead of 1.3.1-ci.N, and nothing + # would restore it. The one temporary override this repository carried, with a machine-enforced + # expiry (breaking -> minor, in .releaserc.json), was worth its cost; a second one, for nothing + # but the cosmetics of an artifact name, was not. label: ci increment: Patch pull-request: diff --git a/README.md b/README.md index e1f6b393..5275acf1 100644 --- a/README.md +++ b/README.md @@ -48,14 +48,11 @@ Everything targets `netstandard2.0` and `net10.0`. ## Status -The 1.0.0 – 1.2.3 releases are **withdrawn from nuget.org**: they were published as stable before the API -had been reviewed against the specifications. **1.3.0 will be the first release whose API is -stable**, and the surface can still change until it is tagged — see -[Versioning](docs/decisions/0001-versioning-and-api-stability.md) for what that window is for. - -Which means there is **nothing to install from nuget.org until 1.3.0 ships**: the `dotnet add -package` lines below have no listed version to resolve, and a withdrawn release comes back only -on an exact version pin. Build from source in the meantime. +**1.3.0 is the first stable release.** From 1.3.0 on the public API follows SemVer: a breaking change costs a +major version, and a deprecation is an `[Obsolete]` member that a later major removes. The 1.0.0 – 1.2.3 +releases were published as stable before the API had been reviewed against the specifications; they are +unlisted and deprecated on nuget.org and should not be used. See +[Versioning](docs/decisions/0001-versioning-and-api-stability.md) for how that came about. ## Install diff --git a/docs/architecture/arc42-CanKit.Pro.md b/docs/architecture/arc42-CanKit.Pro.md index 594cf4c9..874caa23 100644 --- a/docs/architecture/arc42-CanKit.Pro.md +++ b/docs/architecture/arc42-CanKit.Pro.md @@ -151,7 +151,7 @@ Zero-Copy) erhöhen den Aufwand für Q4 und für einen sicheren **Frame-Ownershi ## 2.2 Organisatorische Randbedingungen - **OSS-Paket** (MIT, `LICENSE`), als NuGet-Pakete gemeinsam versioniert und veröffentlicht. Die - Releases 1.0.0 – 1.2.3 sind zurückgezogen; 1.3.0 wird der erste Release mit stabiler API + Releases 1.0.0 – 1.2.3 sind zurückgezogen; 1.3.0 ist der erste Release mit stabiler API (README § Status, `docs/decisions/0001-versioning-and-api-stability.md`). - **Eine CI über die gesamte Solution** (`.github/workflows/ci.yml`; Trigger: Push auf `main`, Pull Requests, `merge_group`). Die adapterweisen Pfadfilter und Solution-Filter der Erstfassung diff --git a/docs/decisions/0001-versioning-and-api-stability.md b/docs/decisions/0001-versioning-and-api-stability.md index 021ff2b5..a1af118f 100644 --- a/docs/decisions/0001-versioning-and-api-stability.md +++ b/docs/decisions/0001-versioning-and-api-stability.md @@ -1,7 +1,7 @@ # Versioning: 1.3.0 is the first stable release -**Status:** accepted, 2026-09-12. Resolves -[#61](https://github.com/dborgards/CanKit.Pro/issues/61). +**Status:** accepted, 2026-09-12; carried out with the release of 1.3.0 on 2026-09-30, see +[Outcome](#outcome) at the end. Resolves [#61](https://github.com/dborgards/CanKit.Pro/issues/61). ## Context @@ -183,3 +183,35 @@ versions. Normal SemVer. A breaking change costs a major version; a deprecation is an `[Obsolete]` member that a later major removes. The API approval tests are what make an accidental break visible in the pull request that causes it. + +## Outcome + +Written on 2026-09-30, after the release; the text above is left as decided. + +1.3.0 was released on 2026-09-30: tag `v1.3.0`, all nine packages on nuget.org, and the changelog +commit `chore(release): 1.3.0` on `main`. + +Against the checklist: + +1. Every `type: bug` issue was closed. The two issues open at the time, [#246](https://github.com/dborgards/CanKit.Pro/issues/246) + (documentation) and [#240](https://github.com/dborgards/CanKit.Pro/issues/240) (a test that failed + once on CI), are not of that type. +2. [#52](https://github.com/dborgards/CanKit.Pro/issues/52) was closed with the normative negative tests. +3. [#23](https://github.com/dborgards/CanKit.Pro/issues/23), [#37](https://github.com/dborgards/CanKit.Pro/issues/37), + [#44](https://github.com/dborgards/CanKit.Pro/issues/44) and [#82](https://github.com/dborgards/CanKit.Pro/issues/82) + had landed. +4. The approval baselines were gone through for shapes that are hard to change later. That review was not + line by line, and it led to three further breaking changes before the tag: `SendConfirmed` became + `SendConfirmedAsync` ([#238](https://github.com/dborgards/CanKit.Pro/pull/238)), and `IProtocolActor.PostAsync` + ([#242](https://github.com/dborgards/CanKit.Pro/pull/242)) and `IIsoTpChannel.SettleAsync` + ([#244](https://github.com/dborgards/CanKit.Pro/pull/244)) gained a `CancellationToken`. +5. Each package README states what is validated and what is not + ([#245](https://github.com/dborgards/CanKit.Pro/pull/245)). + +The pipeline dry run described above failed on its first attempt: the version-resolution step ran +`git push --dry-run` against GitHub in a job that deliberately holds no credentials +([#243](https://github.com/dborgards/CanKit.Pro/pull/243)). It passed after that fix, and 1.3.0 was cut from +the commit it had passed on. + +The `breaking -> minor` override in `.releaserc.json` was reverted to `major` in the change that adds this +section, together with the texts that described the window as open. diff --git a/docs/index.md b/docs/index.md index e9cfe408..057fdc81 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,12 +34,6 @@ designed once instead of improvised in every stack. [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/dborgards/CanKit.Pro/blob/main/LICENSE) -!!! warning "Nothing to install from nuget.org right now" - - 1.0.0 – 1.2.3 are withdrawn, and 1.3.0 is not out yet, so the version badge above reads from - a feed with no listed release and `dotnet add package` has nothing to resolve. Build from - source until 1.3.0 ships. See [Versioning](decisions/0001-versioning-and-api-stability.md). -
diff --git a/docs/packages/index.md b/docs/packages/index.md index 254c0239..d2f9e83f 100644 --- a/docs/packages/index.md +++ b/docs/packages/index.md @@ -8,20 +8,13 @@ description: The nine CanKit.Pro packages, what layer each one lives on, and wha Nine packages, one version number, released together to nuget.org. Take only the layers you need: an ISO-TP application pulls in five of them, a plain demultiplexer one. -!!! warning "1.0.0 – 1.2.3 are withdrawn" +!!! note "1.0.0 – 1.2.3 are withdrawn" These six versions were published as stable before the API had been reviewed against the - specifications, and are unlisted and deprecated on nuget.org. **1.3.0 will be the first - release whose API is stable**; until it is tagged, the public surface can still change. See + specifications, and are unlisted and deprecated on nuget.org. **1.3.0 is the first release + whose API is stable**; use it or later. See [Versioning](../decisions/0001-versioning-and-api-stability.md). - **So there is nothing to install from nuget.org right now.** The `dotnet add package` lines - below have no listed version to resolve until 1.3.0 ships; a withdrawn release comes back - only on an exact version pin, which is not recommended. Build from source in the meantime. - - The version badges in the tables below read from the nuget.org feed, so during this window - they show a withdrawn version or nothing at all. They become meaningful again with 1.3.0. - Everything targets `netstandard2.0` and `net10.0`, so .NET Framework 4.6.2+, .NET 8 and .NET 10 all work. Every package depends on `CanKit.Abstractions` where it touches a bus and on nothing vendor-specific anywhere. diff --git a/docs/release-process.md b/docs/release-process.md index 9a48c73e..06bf82ff 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -32,13 +32,13 @@ Conventional Commits since the last tag: a `fix` bumps the patch, a `feat` the m `BREAKING CHANGE:` footer the major. It then writes the changelog, creates the tag, publishes the GitHub Release and pushes the packages. It only runs on `main`. -!!! note "Until 1.3.0, a breaking change bumps the minor" +!!! note "Since 1.3.0, a breaking change bumps the major" - `.releaserc.json` currently maps `breaking` to a **minor** release, so that the API - corrections on the way to 1.3.0 cannot publish 2.0.0 by accident. This is temporary and is - on the release checklist in - [Versioning](decisions/0001-versioning-and-api-stability.md); - `eng/verify-release-config.mjs` fails the build if the override outlives 1.3.0. + `.releaserc.json` maps `breaking` to **major** again. Until 1.3.0 it mapped to minor, so that the API + corrections before that release could not publish 2.0.0 by accident; how that came about is in + [Versioning](decisions/0001-versioning-and-api-stability.md). + `eng/verify-release-config.mjs` fails the build if the mapping is anything but major now that + 1.3.0 is in the changelog. **GitVersion** answers *"what version is this commit?"* — for builds that are not releases. A pull-request build or a CI artifact from `main` between releases gets a real, ordered SemVer @@ -131,7 +131,7 @@ Each plugin runs in the order it appears in `.releaserc.json`, within each lifec ``` analyze → nothing to release? stop here -verifyRelease → refuse a version below 1.3.0 while the ADR window is open (exec) +verifyRelease → re-check the release configuration for the version about to go out (exec) prepare → CHANGELOG.md regenerated (@semantic-release/changelog) → verify the nine packages `verify` packed (@semantic-release/exec, prepareCmd) → changelog committed and PUSHED to main (@semantic-release/git) @@ -289,17 +289,12 @@ From the Actions tab: **Release → Run workflow**, leaving *dry run* checked. I version, builds, tests and packs, and prints the release notes it would write — without tagging, publishing, or requesting a NuGet credential. -!!! warning "A dry run cannot succeed before 1.3.0" +!!! note "A dry run has something to say only when a release is pending" - The `verify` job refuses any version that is not 1.3.0 while the pre-1.3.0 window is open, and - the commit analyser computes a patch version until a `feat` commit lands. So a dry run today - stops at the version gate, having proved only that version resolution works. - - This is the gate doing its job, not a fault to route around: it refuses to release before the - checklist in [Versioning](decisions/0001-versioning-and-api-stability.md) is done, and a dry - run goes through the same gate as a real one on purpose. The first dry run that exercises the - whole path is the one taken once the version reaches 1.3.0, and 1.3.0 should not be cut until - that has been green. + The version is resolved from the commits since the last tag. If none of them releases (`docs:`, + `test:`, `chore:`, `ci:`, `refactor:`, `style:`), a dry run resolves no version and reports that there + is nothing to release; the build, test and pack steps still run. It prints a version once a `feat`, + a `fix`, a `perf` or a breaking commit has landed. Locally, the same analysis without a token, and without the workflow's gates: diff --git a/src/CanKit.Pro.Actor/README.md b/src/CanKit.Pro.Actor/README.md index 60254704..98ced2d7 100644 --- a/src/CanKit.Pro.Actor/README.md +++ b/src/CanKit.Pro.Actor/README.md @@ -5,11 +5,10 @@ Generic protocol-instance actor/scheduler for [CanKit](https://github.com/pkuyo/ layer (ISO-TP, J1939, CANopen, ...) can build on instead of hand-rolling locks, unsynchronized `List`s, and busy-loop schedulers. -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**; until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The public surface -can still change until then. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See +[Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not diff --git a/src/CanKit.Pro.Addressing/README.md b/src/CanKit.Pro.Addressing/README.md index 1169bad7..3e96ac6b 100644 --- a/src/CanKit.Pro.Addressing/README.md +++ b/src/CanKit.Pro.Addressing/README.md @@ -6,11 +6,10 @@ PDU-Format/Source-Address composition and decomposition, J1939 NAME field access classification helpers, as pure, dependency-free helper functions — no dependency on any other CanKit package. -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**; until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The public surface -can still change until then. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See +[Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not diff --git a/src/CanKit.Pro.CANopen/README.md b/src/CanKit.Pro.CANopen/README.md index 7456f1c4..ab7dd668 100644 --- a/src/CanKit.Pro.CANopen/README.md +++ b/src/CanKit.Pro.CANopen/README.md @@ -1,10 +1,8 @@ # CanKit.Pro.CANopen -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**. Until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The -public surface can still change until then. See +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not diff --git a/src/CanKit.Pro.IsoTp/README.md b/src/CanKit.Pro.IsoTp/README.md index beb3c3ca..2c819c80 100644 --- a/src/CanKit.Pro.IsoTp/README.md +++ b/src/CanKit.Pro.IsoTp/README.md @@ -11,11 +11,9 @@ ISO 15765-2 (ISO-TP) implementation for [CanKit](https://github.com/pkuyo/CanKit Overflow) and enforces N_As/N_Bs/N_Cr timers, reassembles inbound PDUs (SN-checked), and delivers them via `ReceiveAsync` / `ReceiveAllAsync` / `DatagramReceived`. -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**. Until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The -public surface can still change until then. See +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). CAN-FD long-payload cases still get the least coverage of the two halves. diff --git a/src/CanKit.Pro.J1939/README.md b/src/CanKit.Pro.J1939/README.md index e11ac6fe..f8010054 100644 --- a/src/CanKit.Pro.J1939/README.md +++ b/src/CanKit.Pro.J1939/README.md @@ -134,11 +134,9 @@ catalog decodes signed parameters too. ## Status -The 1.0.0 – 1.2.3 releases are **withdrawn from nuget.org** — they were published as stable before the API -had been reviewed. **1.3.0 will be the first release whose API is stable**. Until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The -public surface can still change until then. See +**1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not diff --git a/src/CanKit.Pro.J1939Tp/README.md b/src/CanKit.Pro.J1939Tp/README.md index db1070b5..1a44f968 100644 --- a/src/CanKit.Pro.J1939Tp/README.md +++ b/src/CanKit.Pro.J1939Tp/README.md @@ -2,11 +2,10 @@ SAE J1939-21 Transport Protocol (TP) for CanKit.Pro. Implements both flavors of the J1939-21 §5.10 transport service: -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**; until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The public surface -can still change until then. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See +[Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not diff --git a/src/CanKit.Pro.RawCan/README.md b/src/CanKit.Pro.RawCan/README.md index a7958ef8..9e7bda76 100644 --- a/src/CanKit.Pro.RawCan/README.md +++ b/src/CanKit.Pro.RawCan/README.md @@ -4,11 +4,10 @@ Raw-CAN service layer for [CanKit](https://github.com/pkuyo/CanKit): multi-proto demultiplexing / subscriptions (arc42 §5.3, ADR-5; SRS FR-RAW-010..015) and a TX-confirm abstraction (arc42 §6.3, ADR-7; SRS FR-RAW-030..034). -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**; until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The public surface -can still change until then. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See +[Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not diff --git a/src/CanKit.Pro.Reliability/README.md b/src/CanKit.Pro.Reliability/README.md index af5efa59..c02cda25 100644 --- a/src/CanKit.Pro.Reliability/README.md +++ b/src/CanKit.Pro.Reliability/README.md @@ -6,11 +6,10 @@ checked and fired, and a **bus-state monitor** that pushes `ICanBus.BusState` tr protocol instance — both composed on top of `CanKit.Pro.Actor`'s single-mailbox loop, so there are no free-running timers, no busy loops, and no second background-exception channel. -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**; until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The public surface -can still change until then. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See +[Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not diff --git a/src/CanKit.Pro.Uds/README.md b/src/CanKit.Pro.Uds/README.md index b3415442..d352f342 100644 --- a/src/CanKit.Pro.Uds/README.md +++ b/src/CanKit.Pro.Uds/README.md @@ -5,12 +5,9 @@ directly on top of `CanKit.Pro.IsoTp`'s `IIsoTpChannel`, so anything that speaks (virtual loopback, PCAN, SocketCAN, Vector, Kvaser, ZLG, ControlCAN, ...) can be driven with the same client. -Status: 1.0.0 – 1.2.3 are **withdrawn from nuget.org** — they were published as stable before -the API had been reviewed. **1.3.0 will be the first release whose API is stable**. Until it is -tagged there is no listed version to install, so the `dotnet add package` line below resolves -nothing and the withdrawn releases come back only on an exact version pin. The -public surface can still change until then — `SendRawAsync`, the timing options and the -NRC-mapping types most of all. See +Status: **1.3.0 is the first stable release**: from 1.3.0 on the public API follows SemVer, so a breaking +change costs a major version. 1.0.0 – 1.2.3 were published as stable before the API had been reviewed +against the specifications; they are unlisted and deprecated on nuget.org and should not be used. See [Versioning](https://github.com/dborgards/CanKit.Pro/blob/main/docs/decisions/0001-versioning-and-api-stability.md). ## What is validated, and what is not From 984623535676f0e29a643642aa9faec85ed12257 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 05:33:38 +0000 Subject: [PATCH 3/4] docs: say where the UDS coverage is thin, and record who took the surface as final Two follow-ups to the cleanup after 1.3.0. The Uds README no longer lists types that "can still change", because that belonged to the window before 1.3.0. In its place the validation section says what the tests support: the mapping of negative response codes onto UdsNegativeResponseCode is the thinnest part, with only a few codes asserted by name, while SendRawAsync and the timing options are exercised heavily, like the rest only against the simulated ECU. The sentence first proposed, that these three are the least covered, was checked against the tests and was wrong for two of them, so it was not written. The ADR's Outcome records, under checklist item 4, that the maintainer took the surface as it then stood over as final by starting the release. It says that and no more: the baselines were reviewed, not line by line, and the release was cut after that. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01UWRpkQzKkNDYz3WiNgWvWU --- docs/decisions/0001-versioning-and-api-stability.md | 1 + src/CanKit.Pro.Uds/README.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/decisions/0001-versioning-and-api-stability.md b/docs/decisions/0001-versioning-and-api-stability.md index a1af118f..6cb4a6fd 100644 --- a/docs/decisions/0001-versioning-and-api-stability.md +++ b/docs/decisions/0001-versioning-and-api-stability.md @@ -205,6 +205,7 @@ Against the checklist: `SendConfirmedAsync` ([#238](https://github.com/dborgards/CanKit.Pro/pull/238)), and `IProtocolActor.PostAsync` ([#242](https://github.com/dborgards/CanKit.Pro/pull/242)) and `IIsoTpChannel.SettleAsync` ([#244](https://github.com/dborgards/CanKit.Pro/pull/244)) gained a `CancellationToken`. + The maintainer took the surface as it then stood over as final by starting the release. 5. Each package README states what is validated and what is not ([#245](https://github.com/dborgards/CanKit.Pro/pull/245)). diff --git a/src/CanKit.Pro.Uds/README.md b/src/CanKit.Pro.Uds/README.md index d352f342..4b387f14 100644 --- a/src/CanKit.Pro.Uds/README.md +++ b/src/CanKit.Pro.Uds/README.md @@ -12,7 +12,7 @@ against the specifications; they are unlisted and deprecated on nuget.org and sh ## What is validated, and what is not -**Validated:** Each service listed under *Service coverage* (some of them thinly), negative-response handling and the timing options, by the test suite in `tests/CanKit.Pro.Tests`, against `SimulatedUdsEcu` — a scripted ECU simulation in this repository whose responses each test defines — over `CanKit.Adapter.Virtual`. +**Validated:** Each service listed under *Service coverage* (some of them thinly), negative-response handling and the timing options, by the test suite in `tests/CanKit.Pro.Tests`, against `SimulatedUdsEcu` — a scripted ECU simulation in this repository whose responses each test defines — over `CanKit.Adapter.Virtual`. The thinnest coverage is the mapping of negative response codes onto `UdsNegativeResponseCode`: only a few codes are asserted by name. `SendRawAsync` and the timing options are exercised heavily, but likewise only against the simulation. **Not validated:** Any real ECU, whose timing, negative-response usage and deviations from the standard the simulation does not reproduce, and conformance as a tester would judge it. Nothing in this package has run against real CAN hardware, a conformance tester or a third-party implementation: the test project references `CanKit.Adapter.Virtual` and no hardware adapter. From 1bff191823e89fefd441df23b11ff28c55b214aa Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 05:35:47 +0000 Subject: [PATCH 4/4] docs: correct what a dry run does when no release is pending The note added in the cleanup after 1.3.0 said the build, test and pack steps still run when no releasing commit has landed, and listed feat, fix, perf and breaking commits as the ones that produce a version. Both were written without looking at the workflow and the release rules. release.yml skips the Pack and Upload steps when no version resolves, so such a dry run builds and tests and does not exercise package creation. And .releaserc.json also maps revert and build(deps) to a patch release, which the list left out. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01UWRpkQzKkNDYz3WiNgWvWU --- docs/release-process.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/release-process.md b/docs/release-process.md index 06bf82ff..025905ef 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -293,8 +293,10 @@ publishing, or requesting a NuGet credential. The version is resolved from the commits since the last tag. If none of them releases (`docs:`, `test:`, `chore:`, `ci:`, `refactor:`, `style:`), a dry run resolves no version and reports that there - is nothing to release; the build, test and pack steps still run. It prints a version once a `feat`, - a `fix`, a `perf` or a breaking commit has landed. + is nothing to release. Build and test still run, but the Pack and Upload steps are skipped, because + they need a version: such a dry run does not exercise package creation. It resolves a version once a + commit of a releasing type has landed: `feat`, `fix`, `perf`, `revert`, `build(deps)`, or any breaking + commit. Locally, the same analysis without a token, and without the workflow's gates: