docs: ICM lifecycle and API compatibility governance draft#497
Merged
hdamker merged 21 commits intoMay 26, 2026
Conversation
Draft response to the ICM WG request to Release Management (ICM#324, ICM#340, RM#351/camaraproject#459) defining governance for ICM version evolution and its dependencies with CAMARA API versions. Built on a three-contract model (API Consumer ↔ API, API Consumer ↔ AS, ICM ↔ API), semver discipline at ICM 1.0.0, per-major lifecycle tiers (Preferred/Supported/Deprecated/Retired), a flat x-camara-min-icm-version declaration in API specs, a derived compatibility matrix, and explicit recognition of aggregators as ecosystem normalizers.
hdamker
requested review from
rartych,
soadeyemo and
tanjadegroot
as code owners
tanjadegroot
left a comment
tanjadegroot
left a comment
Collaborator
There was a problem hiding this comment.
First set of comments before going any further. In general:
I think we need to decouple this document from implementations of ICM (auth server, certificate authority, etc.).
There is only 1 contract for API consumers: the API version definition (which includes its declared minimum ICM version expressing its compatibility).
API providers must ensure to offer ICM-compatible API version implementations at all times (and hence update their ICM implementation. I prefer to
- remove reference to AS / certificate authorities, only refer to ICM or ICM version
- remove the notion of API - ICM contract, use instead the term ICM-compatibility.
- remove triangle relationship to simplify.
I prefer to use lifecycle state instead of lifecycle tier (more usual for understanding).
The "orthogonal API" concept, seems to be in contradiction with the objective to move API forward and deprecate ICM versions. I would prefer to drop it as anyway has only 5 occurrences - 2 of which in the definition itself and others can easily be dropped, so the additional concept and definitions are superfluous.
But maybe we need a x-camara-minimum-icm special value if "not applicable" or "any" (or 1.0.0" ? for APIs that are ICM-compatible by default (independently of the version) ? This could make it more clear for ICM implementation evolution, which API version implementations need to be upgraded.
I reviewed up to section 5 along the above lines.
Collapse to one defined ICM-compatibility concept (API spec relative to ICM version), use 'state' instead of 'tier' for ICM major lifecycle, require lowest Supported ICM version as the publication-time floor, and distinguish technical compatibility from CAMARA compliance.
Collaborator
Author
|
Hi @tanjadegroot, thanks for your review ... I expect that we will need the one or other round to converge the document. I have applied in commit eff45e5 most of your suggested changes. Below is a status per suggestion:
|
Collaborator
Author
Considered and not introduced. The lowest-Supported-at-publication rule in §7.2 achieves the practical goal without a permanent floor that could encourage API Providers to keep outdated ICM versions in operation. For APIs that need to declare compatibility across multiple ICM majors explicitly, §7.3 proposes an optional x-camara-icm-compatibility field which can be added and updated via patch releases. |
tanjadegroot
left a comment
tanjadegroot
left a comment
Collaborator
There was a problem hiding this comment.
reviewed up to section 6.2.
will continue after updated DRAFT that includes per the discussed ICM V2 (Wiki) is included.
- §3 restructured around two distinct aspects of ICM-compatibility: API version (design-time, CAMARA-governed via Commonalities) and deployment (runtime, API-Provider-governed). Explicit ICM → Commonalities → API definitions path captured in §3.4. - §6.1 state model recast as a four-column table (state × ICM version × API version × API deployment). States apply per ICM version with major as the primary grain. Revoked added as a terminal exceptional state. Preferred kept as a label (deployment recommendation only). - API spec field is `x-camara-min-icm` (no `-version` suffix). §7.2 rule includes a third operand: the ICM floor required by the declared Commonalities version. - §10 cascade section dropped — its consequences are now captured by the four-column state table; remaining unique point on API-lifecycle independence moved to §6.1 as a note. §7.3 (multi-major declaration field) also dropped; cross-major compatibility is handled solely by §4 governance assessment. - §6.4 introduces breaking-change tables (design info and deployment info) as ICM release-note stubs. - §14 open items reworked: added cross-major assessment process and timing, Provider deployment timeline after Preferred designation, and ICM ↔ Commonalities coupling. - Glossary aligned with WG review; SemVer capitalization consistent throughout; MUSTs scope-clarified for CAMARA-governance reach.
Tanja's reply on PR camaraproject#497 confirms dropping the Preferred concept entirely. Migration timing on the deployment side is governed by the lifecycle state transitions (Supported → Deprecated → Retired window), decoupled from meta-release cadence. Changes: - Remove the Preferred glossary entry and the Preferred paragraph in §6.1. - §6.2: reword the row labels and notes so timing triggers off the publication of a newer Supported major rather than off a Preferred-label transition; reword the concurrent-support requirement accordingly. - §8 item 1: API Providers MUST implement the latest published Supported major ICM version (instead of 'the version holding the Preferred label'). - §14: drop the now-redundant open item on Provider deployment timeline after Preferred designation; covered by item 1 (exact durations).
…ity.md Co-authored-by: Tanja de Groot <87864067+tanjadegroot@users.noreply.github.com>
tanjadegroot
left a comment
tanjadegroot
left a comment
Collaborator
There was a problem hiding this comment.
First set of comments
|
|
||
| An ICM change that invalidates existing deployment implementations is a major-version event even if no API definition requires re-release. Semver discipline is not satisfied by preserving API version ICM-compatibility alone. | ||
|
|
||
| The transition to 1.0.0 should coincide with a scope-baseline review of the ICM documents, declaring the then-current definitions as the stable starting point. Pre-1.0 versions are handled by the Legacy section (§12). |
Collaborator
There was a problem hiding this comment.
this comment should go to an "ICM version governance" section. it is a project issue, not part of the general process description.
Collaborator
Author
There was a problem hiding this comment.
Applied in 5bca022 — folded into §12 item 2 (Open governance decisions: "Transition to ICM 1.0.0"). Happy to relocate if a different governance section fits better.
tanjadegroot
left a comment
tanjadegroot
left a comment
Collaborator
There was a problem hiding this comment.
all comments - had to do in detail sorry
Wording polish from Tanja's 2026-05-18 review: standardise on 'API version ICM-compatibility' / 'API deployment ICM-compatibility' throughout; rename headings (§3.3, §5, §7.2, §7.3, §8, §10, §11.1-§11.3); reorder §5 SemVer bullets major → minor → patch; update lifecycle-state table rows; drop §10.3 (folded into §10.1/10.2); reword §6.2 governance parameters; add 'documented by Release Management' intro to §13. Structural changes (merge §4 → §7, §6 transitions subsection split, §12 lifecycle column) and pushback items left in 23 open threads.
§4 (Minimum ICM version) folded into §6.1 of the renamed §6 (API version ICM-compatibility - details). Floor declaration, three bullets, cross-major governance assessment, and example consolidated into a single subsection. Sections §5..§14 renumber down to §4..§13; all cross-refs updated.
Current §5.4 (Publication of state) and §5.5 (release-note change tables) combined under a single §5.4 "ICM version - Release notes" parent with §5.4.1 (Publication of lifecycle state) and §5.4.2 (ICM version change tables) as sub-subsections. §13 item 10 cross-ref updated to §5.4.2.
- §5.1 Revoked row: broaden 'a later minor or patch version' to
'another (earlier or later) minor or patch version' to allow rollback.
- §7.1 item 3: remove the 'info.description template mandated by
Commonalities' clause from the Provider discovery channels
(the template does not advertise the deployed ICM version).
- §4 trailer ('transition to 1.0.0 should coincide with a scope-baseline
review...') folded into §12 item 2 (Transition to ICM 1.0.0).
- §5.3 governance-parameters trailer: annotated with HTML comment marker
for removal when WG agrees.
- §8 Aggregator role removed — no normative content. §9..§13 renumbered
to §8..§12; all cross-refs updated.
- Appendix B removed.
- §6.2 floor formula commentary: drop 'latest' and 'major' qualifiers on 'always raises its x-camara-min-icm to a Supported ICM version'. Remove Tanja's TBC meta-marker. - §5.4.1 machine-readable schema: tighten 'may be defined later' to 'must be available' (the §6.3 validation rule depends on it). - §6.3 validation: add explicit dependency note pointing at §5.4.1. - §9.1 ICM-compatibility formula: add () around the AND triple; fix unmatched ')' typo. - §11 line 317: 'ICM-compatibility changes' → 'ICM-compatibility authorizations' (matches glossary §2). - §5.1 Revoked row note and §7.1 provider-compliance line: drop redundant 'major' qualifier (applies to any ICM version).
- §2 glossary:
- ICM deployment info: broaden scope to include design time, not
only runtime, since Providers and Consumers design their
implementations against the target ICM version.
- API version ICM-compatibility: tie the property to the
x-camara-min-icm field where the floor is declared.
- 'Deployment ICM-compatibility' → 'API deployment ICM-compatibility'
to match the prefix used throughout the body.
- ICM-compatibility umbrella: name the two members explicitly
(API version + API deployment ICM-compatibility) instead of the
abstract 'aspects' shorthand.
- §3 heading: drop the '— two aspects, two responsibilities' subtitle.
- §3 intro paragraph: name ICM design info and ICM deployment info
upfront, hooking into the §3.1 / §3.2 subsections.
- §3.1 'Owned and governed by CAMARA' bullet: keep 'codified by';
add trailing clarifier '… by following these guidelines.'
- §3.1 second bullet: 'Signaled by x-camara-min-icm declared in' →
'Declared via x-camara-min-icm in'.
Collaborator
Author
|
Update — five more commits:
A handful of threads remain open — see inline replies for the cases where the apply deviated from your literal suggestion. |
I could not commit to a new branch and do a PR: error message: 'There was an error committing your changes: File could not be edited'
Updated sections on ICM version release cadence and compatibility matrix for clarity and precision.
inverted order of old sections 10 and 11
tanjadegroot
approved these changes
May 26, 2026
tanjadegroot
left a comment
tanjadegroot
left a comment
Collaborator
There was a problem hiding this comment.
looks good ! (I saw only 2 changes)
hdamker
commented
May 26, 2026
hdamker
commented
May 26, 2026
hdamker
commented
May 26, 2026
hdamker
commented
May 26, 2026
hdamker
commented
May 26, 2026
hdamker
commented
May 26, 2026
Collaborator
Author
|
Proposal for next steps:
|
Co-authored-by: Herbert Damker <herbert.damker@telekom.de>
hdamker
merged commit 3cd35c1
into
camaraproject:docs/icm-lifecycle-compatibility
1 check passed
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
2 participants
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.
What type of PR is this?
What this PR does / why we need it:
Adds a draft governance document for ICM version evolution and its dependencies with CAMARA API versions, placed under
documentation/SupportingDocuments/. Agreed by the Release Management WG to serve as the base for further discussion in response to the ICM WG's request to define release governance between ICM and APIs.Key elements:
x-camara-min-icm-versiondeclaration in API specs, publication-time fixedOpen governance decisions (durations, exception process, interaction with certification) are listed in §15 for WG discussion.
Which issue(s) this PR fixes:
Relates to #351 and #459. Also related: camaraproject/IdentityAndConsentManagement#324 and camaraproject/IdentityAndConsentManagement#340.
Special notes for reviewers:
This is a draft for WG discussion. §15 lists the open governance decisions that need WG agreement before adoption. Feedback welcome inline or as review comments.
Changelog input
Additional documentation
None.