Skip to content

docs: fix stale references left by the API split (#184) - #186

Merged
clundie-CL merged 1 commit into
camaraproject:mainfrom
caubut-charter:184-stale-reference-cleanup
Aug 26, 2026
Merged

docs: fix stale references left by the API split (#184)#186
clundie-CL merged 1 commit into
camaraproject:mainfrom
caubut-charter:184-stale-reference-cleanup

Conversation

@caubut-charter

Copy link
Copy Markdown
Contributor

What type of PR is this?

  • documentation

What this PR does / why we need it:

Fixes stale references left behind by the API split. The repository used to define one monolithic
network-access-management API; #153 split it into network-access-devices and
network-access-domains, but several references to the pre-split world — and several documents
that had drifted from the tree — were never updated.

Old API name where a split API name is required

  • TrustDomainsUser_Story.md said the API Provider must have implemented the "Network Access
    Management (NAM)" API. It is the Network Access Domains API, as the sibling
    device-registration story already states correctly.
  • code/Test_definitions/README.md described a single API; the directory covers both.
  • Five schema descriptions placed their resource "within the network access management system";
    each now names the API that actually exposes it.

Documented behaviour that does not exist

  • TrustDomainsUser_Story.md listed 409 Conflict (INCOMPATIBLE_STATE) for Trust Domain deletion.
    deleteTrustDomain documents 204/400/401/403/404/500/503 and no 409 at all; the only 409 in that
    spec is ALREADY_EXISTS on creation. Replaced with the exception the spec actually defines.
  • DeviceRebootRequest_User_Story.md omitted 409 ALREADY_EXISTS, 409 INCOMPATIBLE_STATE and
    422 MISSING_IDENTIFIER, all of which the devices spec does document. Added.

code/README.md drift

  • The folder tree omitted Test_definitions/ and three of the four files in common/.
  • The Component Breakdown table listed 5 of the 11 component files. It now lists all of them with a
    "Used by" column, produced by resolving every $ref transitively from both specs.
  • NAM_Common.yaml's contents were described three different ways in three places, none of them
    complete. Reconciled against the file.
  • Removed two redundant restatements so each component is described exactly once.

Reference fix — the root README pointed at a non-existent local APIBacklog.md; now links to
the file in camaraproject/APIBacklog.

Which issue(s) this PR fixes:

Fixes #184

Does this PR introduce a breaking change?

  • Yes
  • No

Special notes for reviewers:

Reported, deliberately not fixed here:

  • CHANGELOG.md:30,31,32,57 — four links point at camaraproject/DeviceIdentifier /
    device-identifier.yaml instead of this repository, a bootstrap template copy-paste. Not edited:
    released history, and /CHANGELOG.md requires release-management review.
  • Both specs reference an "API Readiness Checklist" document that does not exist anywhere under
    documentation/. Not edited: the sentence sits inside a CAMARA:MANDATORY block, so the fix
    belongs upstream in Commonalities or in actually adding the document.
  • Two user stories link TMF640 at projects.tmforum.org, a retired Confluence instance, and
    documentation/API_documentation/README.MD:15 links a login-gated engage.tmforum.org download.
    Not changed — no verified replacement URLs.
  • README.md:12 says the repository "does not yet belong to a CAMARA Sub Project" while lines
    49–50 refer to "this Sub Project" and the sp-nam mailing list. Likely CAMARA-managed
    boilerplate, so left alone.
  • code/Test_definitions/README.md:111 — a lint recipe labelled "from anywhere" whose last
    argument is a repo-relative path, so it only works from the repository root.

Changelog input

release-note Corrected documentation left stale by the API split: pre-split API names in user stories and schema descriptions, a Trust Domain deletion exception documenting an undefined 409, missing reboot-request error responses, and an out-of-date component inventory in code/README.md.

Additional documentation

This section can be blank.

docs

The repository used to define one monolithic `network-access-management`
API. PR camaraproject#153 split it into `network-access-devices` and
`network-access-domains`, but several references to the pre-split world, and
several documents that had drifted from the tree, were never updated.

Old API name where a split API name is now required:

- `TrustDomainsUser_Story.md` said the API Provider must have implemented the
  "Network Access Management (NAM)" API; it is the Network Access Domains
  API, as the sibling device-registration story already states.
- `code/Test_definitions/README.md` described a single API; it covers both.
- Five schema descriptions placed their resource "within the network access
  management system"; each now names the API that actually exposes it.

Documented behaviour that does not exist:

- `TrustDomainsUser_Story.md` listed `409 INCOMPATIBLE_STATE` on Trust Domain
  deletion. `deleteTrustDomain` documents 204/400/401/403/404/500/503 and no
  409 at all; the only 409 in that spec is `ALREADY_EXISTS` on creation.
  Replaced with the exception the spec actually defines.
- `DeviceRebootRequest_User_Story.md` omitted the `409 ALREADY_EXISTS`,
  `409 INCOMPATIBLE_STATE` and `422 MISSING_IDENTIFIER` responses that the
  devices spec does document. Added.

`code/README.md` drift:

- The folder tree omitted `Test_definitions/` and three of the four files in
  `common/`.
- The Component Breakdown table listed 5 of the 11 component files. It now
  lists all of them, with a "Used by" column stating which API pulls each one
  in; this was verified by resolving every `$ref` transitively from both
  specs.
- `NAM_Common.yaml`'s contents were described three different ways in three
  places, none of them complete. Reconciled against the file.
- Removed two now-redundant restatements of the same facts so each component
  is described once.

Reference fixes: the root README pointed at a non-existent local
`APIBacklog.md`, now linked to the file in camaraproject/APIBacklog.
@caubut-charter
caubut-charter force-pushed the 184-stale-reference-cleanup branch from f64a314 to 35c196a Compare August 25, 2026 17:06

@clundie-CL clundie-CL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. The one note is that for you PR trio the merge order is #186#185#187. In view of #180, I think that becomes #180#186#185#187

@clundie-CL
clundie-CL merged commit 9b88638 into camaraproject:main Aug 26, 2026
2 checks passed
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.

Stale references after API split

2 participants