Document new versioning scheme and bump mainline to v5.0.0

[samuel40791765]

Issues:

Resolves P425126007

Description of changes:

AWS-LC does not currently document its versioning scheme or release
types for external consumers. This change adds VERSIONING.md at the
repo root describing the AWS-LC version number scheme, the FIPS version
number, the distinction between rolling mainline and LTS releases, the
LTS release policy, non-LTS FIPS branches, branch naming conventions,
and deprecation timelines for legacy FIPS branches.

Also bumps mainline from v1.72.1 to v5.0.0 to reflect that the 4.x line
now belongs to the first LTS branch (fips-2025-09-12-lts) under the
new versioning scheme.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.15%. Comparing base (4207584) to head (363a546).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3212      +/-   ##
==========================================
- Coverage   78.30%   78.15%   -0.16%     
==========================================
  Files         689      689              
  Lines      123310   123334      +24     
  Branches    17150    17173      +23     
==========================================
- Hits        96564    96387     -177     
- Misses      25835    26035     +200     
- Partials      911      912       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[justsmth]

• Should we point consumers to our AWSLC_API_VERSION macro or ABI_VERSION as better indicators of compatibility breaking changes than the version number? Should this policy also cover our use of these values? (Should ABI_VERSION be exposed in our header files as well?)
• I think we should state explicitly that our versioning is NOT SemVer:

Mainline does not follow SemVer with respect to major-version bumps; ABI may
change between minor releases on mainline. Consumers requiring ABI stability
should pin to an LTS branch.

[samuel40791765]

Applied most wording updates.

Good point on ABI_VERSION. Although, I'm slightly unsure on how we've committed to updating this and exposing would require better knowledge of how we're planning to document and maintain the API.

[justsmth]

The "Most of these branches are not designated as LTS" introduces some ambiguity. Instead, should we clarify that a branch is marked "LTS", or not, at time of creation -- a branch is never "promoted"?

An LTS branch is always cut fresh from mainline at the time of designation;
existing non-LTS branches are never promoted to LTS.

[justsmth]

It seems to be implied, but could be made explicit. I think the intent is:

• Feature Additive (signature-preserving) changes --> minor bump
• Security / Bug / Platform (possibly not signature-preserving) fixes --> patch bump

[samuel40791765]

Restructured the above a bit to reflect that clearly

[justsmth]

I think we could spell this out even more:

We may apply critical security fixes to a non-LTS FIPS branch only while 
it is in review and until it is the most recently NIST-certified FIPS branch.
This is a maintenance concession; these branches are NOT supported for
consumption. Once a newer FIPS branch (whether LTS or non-LTS) receives NIST
certification, the previous non-LTS branch is frozen and will receive no
further updates.

[justsmth]

We could add another sentence at the end of this paragraph:

Note that at the branch point, both mainline and the non-LTS branch share the
same AWS-LC version string; they are distinguished by `FIPS_version()` and
`AWSLC_FIPS_VERSION_NUMBER`.

[samuel40791765]

I reworded it slightly, but added a sentence that should reflect what we're looking for here.

[justsmth]

NP: I don't know that we could do anything about it -- but what if CVE fix fundamentally requires us to change a function signature or add a field to a stack-allocatable struct? We'd be force to choose between patching the CVE or not breaking ABI?

¯\_(ツ)_/¯

[samuel40791765]

Great point, I had briefly thought about this and there were mentions that there were possible workarounds around this. In most cases, the LTS branch can ship a custom patch that fixes the same security issue while preserving ABI compatibility (even when mainline's version doesn't) by using a more minimal patch, side state, or wrapper variant rather than restructuring existing types.

Of course, there could be edge cases where none of those approaches fit and we'd be forced into the trade-off scenario you described. If it comes to that, we could treat them as one-offs and decide on the appropriate approach based on the specific circumstance.

[justsmth]

NP: Should there be an API or Macro (or both) to indicate at build or runtime whether this version of AWS-LC is an LTS?

Of course, at build or runtime a consumer can compare AWSLC_FIPS_VERSION_NUMBER with AWSLC_VERSION_NUMBER_STRING -- if they align, then we're on an LTS. Should we call this out? Or provide a function that does this?

[samuel40791765]

Should there be an API or Macro (or both) to indicate at build or runtime whether this version of AWS-LC is an LTS?

I think an LTS designation API may be worth doing if the need arises. Happy to take up explicit LTS detection in a separate PR if we want it.

I do want to call out that It would have to be its own value that's set and returned however. The comparison only works today because LTS-1 was coincidentally cut at major 4 with FIPS submission 4. As non-LTS submissions accumulate, the heuristic breaks down:

Event	Mainline (major / FIPS)	LTS-1 (major / FIPS)	LTS-2 (major / FIPS)
Today	5 / 4	4 / 4	—
Non-LTS #5 cut	5 / 5	4 / 4	—
Non-LTS #6 cut	5 / 6	4 / 4	—
Non-LTS #7 cut	5 / 7	4 / 4	—
LTS-2 cut at FIPS 8	6 / 8	4 / 4	5 / 8

When the second LTS is cut, its major (5) and FIPS submission (8) don't align, so the comparison would break.