Skip to content

docs(v4): fill in missing variant field coverage#128

Merged
ashleythedeveloper merged 1 commit into
masterfrom
docs/v4-field-coverage
May 28, 2026
Merged

docs(v4): fill in missing variant field coverage#128
ashleythedeveloper merged 1 commit into
masterfrom
docs/v4-field-coverage

Conversation

@ashleythedeveloper

Copy link
Copy Markdown
Contributor

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.

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 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, 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 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 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.
  • No app/ code. No new endpoints. No DTO changes.
  • The :4.0.0 and :latest Docker tags are unchanged (they move on tag pushes, not master pushes).

Test plan

  • yarn build in documentation/ (Docusaurus build clean, no broken links).
  • diff -rq documentation/docs/ documentation/versioned_docs/version-4.0.0/ returns no differences.
  • Field reference cross-checked against app/src/modules/link-registration/dto/link-registration.dto.ts and app/src/modules/link-registration/constants/untp-enums.ts (every DTO-accepted field is in the table; enum values for encryptionMethod and accessRole shorthand expansion are accurate).
  • itemDescription alias claim verified against the existing e2e suite at app/test/link-registration/item-description-backwards-compat.e2e-spec.ts.

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.
@ashleythedeveloper ashleythedeveloper merged commit 864771f into master May 28, 2026
7 checks passed
@ashleythedeveloper ashleythedeveloper deleted the docs/v4-field-coverage branch May 28, 2026 22:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant