Release Review: NumberRecycling r3.1 (rc Sync26)

[camara-release-automation]

Release Review: r3.1 rc

This PR finalizes the reviewable release content for the active snapshot.

Edit and review this PR before merging it into the release snapshot. After Codeowner and Release Management approval, merging this PR creates the draft release.

Release contents

API	Version	Status	Comparison target
number-recycling	0.3.0-rc.1	rc	0.2.0

Dependencies: Commonalities r4.3, ICM r4.2

Codeowner Actions

Tick each box once done. Release Management review starts when all three boxes are ticked.

• Update the CHANGELOG

  What to do:

  • Copy all API-consumer-relevant changes from the provided list into the appropriate Breaking changes / Added / Changed / Fixed / Removed sections for each API. List breaking changes both in Breaking changes and in their normal change category.
  • Do not copy administrative, tooling-only, or internal maintenance changes unless they affect API consumers.
  • For each API, fill the CHANGELOG against the stated comparison target, following the release-type rules at the top of the CHANGELOG.

• Document deferred validation warnings (and hints)

  What to do:

  • Check the CAMARA Validation comment on this PR for warnings and hints.
  • For each warning you do not fix, document it in an issue: include a copy of the validation summary line(s) and the reason the fix is deferred.
  • Document in the same way any validation hint that is applicable to the API and needs to be fixed later.
  • You may group several findings into one issue or split them across issues — either is fine.
  • List the documenting issue(s) in a comment on this PR.
  • Note: documenting deferred warnings is optional but recommended for alpha pre-releases, and mandatory for rc pre-releases and public releases.

• The release is ready for Release Management review

  Check that:

  • All mandatory release assets for the declared status(es) are present (see the table below "Required release assets per API status" by expanding the arrow);
  • API documentation and test cases are adequate for the target status.

  Tick this box to confirm readiness and to start the Release Management review.

Release Management Actions

• CHANGELOG follows the release documentation rules
• Breaking changes are documented and version updates follow SemVer rules
• Mandatory release assets are present for each API according to its status
• All remaining validation warnings are documented in issues and the reasons for deferral are defensible

Required release assets per API status

Nr	Asset	alpha	rc	initial public	stable public
1	Release Plan	M	M	M	M
2	API Definition(s)	M	M	M	M
3	Commonalities compliance	O	M	M	M
4	API Documentation	M	M	M	M
5	User Stories	O	O	O	M
6	Test Cases (basic)	O	M	M	M
7	Test Cases (enhanced)	O	O	O	M
8	API Description	O	O	M	M

M = Mandatory, O = Optional — Full documentation

Valid next actions for codeowners

• Merge this PR when all Codeowner Actions and Release Management Actions are complete and the required approvals are present — creates the draft release
• Use /discard-snapshot <reason> in the Release Issue to discard this snapshot, return to planned, and update content on main

---

Snapshot: r3.1-e8e9094

[camara-validation]

CAMARA Validation — PASS (with warnings)

0 errors, 1 warnings, 0 hints | Profile: standard

View full results

Warnings MUST be documented in one or more issues before this release — see the Codeowner Actions in the PR description.

[albertoramosmonagas]

Hi all, just to clarify the versioning point: I would not consider the changes introduced in PR #106 a breaking change. The PR does not change the API contract or conformance behavior:

• no endpoint has changed,
• no request or response schema has changed,
• phoneNumberRecycled remains a boolean,
• 400 OUT_OF_RANGE already existed in the API,
• and no conformance tests have been modified to enforce a new runtime behavior.

The changes are therefore documentation / semantic clarification, aligning the API guidance with the agreed whitepaper interpretation of specifiedDate and the existing OUT_OF_RANGE response. If in a future release we decide to make a different response mandatory for a scenario that existing implementations currently handle differently, and enforce that through conformance tests, then we should assess that separately as a potential behavioral breaking change.

[Masa8106]

@albertoramosmonagas, Thank you for your comment.
First of all, I am not sure what is the definition of breaking change exactly.
As you pointed out, there is no change from aspects of API specificatoin (though Scenario 2 in yaml file was changed) and test feature file.
On the other hand, a response value was changed in a specific case. From API consumer perspective, there is a difference between v0.2 and v0.3. I think it can't be covered by v0.3 and it is a change of non-backward compatibility.
So far I can discuss openly whether this is a breaking change or potential behavioral breaking change.

[albertoramosmonagas]

You're correct that the Scenario 2 description changed relative to what the v0.2.0 YAML literally stated. However, I would like to add context that I believe is relevant for the classification.

This scenario represented an open behavioral point in the API — one where the expected response was not unambiguously settled across implementations. The whitepaper resolved that ambiguity through an alignment process across operators. PR #106 carries that agreed clarification into the YAML.

In that framing, this is a clarification of previously underspecified behavior, not the introduction of a new behavioral constraint that breaks existing consumers. The distinction matters for CHANGELOG purposes: a breaking change signals to consumers that something that worked against v0.2.0 will fail against v0.3.0. That is not the situation here — what changed is that an open question now has a definitive answer.

[eric-murray]

@camaraproject/number-recycling_maintainers, @camaraproject/number-recycling_codeowners
With the updated validation rules, the unused schema Generic200 is now a warning rather than a hint. So it should be used or deleted. I would suggest to delete it as there really isn't such a thing as a "Generic" 200 response for CAMARA APIs.

[Masa8106]

@eric-murray, thank you for your suggestion. Please let me delete Generic200 schema.