docs(v4): fill in missing variant field coverage#128
Merged
Conversation
The v4.0.0 release-prep PR (#127) shipped without documenting three landings that are part of v4 but went unmentioned in the release notes and the docs site: the additive `public` and `rel` variant fields, and the MIME type loosening (the service now accepts any RFC 6838 well-formed media type, not the previous curated list). A canonical per-variant field reference was also missing entirely; the developer-guide described variants through a single registration example, leaving `method`, `encryptionMethod`, and registration-time `accessRole` undocumented since v2.0.0. This PR fills those gaps without changing any code, version, or release tag (v4.0.0 already supports everything described here; the docs were lagging the binary). - `documentation/docs/developer-guide/index.md`: new "Variant fields" reference table covering every accepted field with type, required/optional, and contract notes. Includes the `predecessor-version` strip semantics on `rel`. MIME paragraph and prose intro updated for RFC 6838 acceptance and `hreflang[]`. Pointer to the Swagger UI as the authoritative DTO surface. Stale `itemDescription will be removed in v3.0` note corrected (the field remains accepted as an alias). - `documentation/docs/understanding-the-service/how-it-works.md`: Language and MIME bullets in the variant-model section updated; new paragraph naming `public`, `rel`, `accessRole`, `encryptionMethod`, `method` and linking to the field reference. - `documentation/docs/migration-guides/v4.md`: new "Additive variant fields and MIME loosening" subsection alongside the existing breaking-change subsections in "What changed". - `RELEASE_NOTES.md`: peer subsection in v4.0.0's "What changed" block covering the same three additive landings. - `documentation/versioned_docs/version-4.0.0/...`: mirror of every change above so the served 4.0.0 docs match. Snapshot is byte-identical to current docs (`diff -rq` clean). No `version.json`, `app/package.json`, `docusaurus.config.ts`, or `versions.json` changes. v4.0.0 remains v4.0.0; the image at `ghcr.io/.../pyx-identity-resolver:4.0.0` is unchanged.
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
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.
The v4.0.0 release-prep PR (#127) shipped without documenting three landings that are part of v4 but went unmentioned in the release notes and the docs site: the additive
publicandrelvariant fields, and the MIME type loosening (the service now accepts any RFC 6838 well-formed media type, not the previous curated list). A canonical per-variant field reference was also missing entirely; the developer-guide described variants through a single registration example, leavingmethod,encryptionMethod, and registration-timeaccessRoleundocumented since v2.0.0.This PR fills those gaps without changing any code, version, or release tag. v4.0.0 already supports everything described here; the docs were lagging the binary.
What this PR changes
documentation/docs/developer-guide/index.md: new Variant fields reference table covering every accepted field with type, required/optional, and contract notes. Includes thepredecessor-versionstrip semantics onrel. MIME paragraph and prose intro updated for RFC 6838 acceptance andhreflang[]. Pointer to the Swagger UI as the authoritative DTO surface. Stale "itemDescription will be removed in v3.0" note corrected (the field remains accepted as an alias, confirmed by the existing e2e suite).documentation/docs/understanding-the-service/how-it-works.md: Language and MIME bullets in the variant-model section updated; new paragraph namingpublic,rel,accessRole,encryptionMethod,methodand linking to the field reference.documentation/docs/migration-guides/v4.md: new### Additive variant fields and MIME looseningsubsection alongside the existing breaking-change subsections in "What changed".RELEASE_NOTES.md: peer subsection in v4.0.0's "What changed" block covering the same three additive landings.documentation/versioned_docs/version-4.0.0/...: mirror of every change above so the served4.0.0docs page matches the current docs.diff -rq documentation/docs/ documentation/versioned_docs/version-4.0.0/is clean.What this PR does NOT change
version.json,app/package.json,documentation/package.json,documentation/versions.json,documentation/docusaurus.config.ts. v4.0.0 stays at v4.0.0.app/code. No new endpoints. No DTO changes.:4.0.0and:latestDocker tags are unchanged (they move on tag pushes, not master pushes).Test plan
yarn buildindocumentation/(Docusaurus build clean, no broken links).diff -rq documentation/docs/ documentation/versioned_docs/version-4.0.0/returns no differences.app/src/modules/link-registration/dto/link-registration.dto.tsandapp/src/modules/link-registration/constants/untp-enums.ts(every DTO-accepted field is in the table; enum values forencryptionMethodandaccessRoleshorthand expansion are accurate).itemDescriptionalias claim verified against the existing e2e suite atapp/test/link-registration/item-description-backwards-compat.e2e-spec.ts.