Feature: Governed Semantic Versioning with CI integration (Major = upstream break; fork‑aware signaling)

[svelderrainruiz]

Feature Request: SemVer policy with LabVIEW-gated majors + fork compatibility signal

Summary

Adopt a formal Semantic Versioning policy where Major bumps occur only when upstream LabVIEW forces a breaking API change. Use this to give contributors and forks a clear signal about compatibility and breaking changes.

Problem

Today’s versioning is ad-hoc, which means:

• Breaking changes aren’t obvious to users or integrators.
• Forks drift silently; there’s no quick way to tell if a fork has introduced breakage vs. upstream.
• Tooling/CI can’t trust versions to decide which tests/release tracks to run.
• NI sometimes prefers year-based majors; our stance needs to be explicit.

Goals

• Make Majors a reliable indicator of breaking changes (triggered by LabVIEW).
• Keep Minors for features and Patches for fixes.
• Provide a fork-to-fork compatibility cue via SemVer deltas.
• Keep CI artifacts traceable to exact commits.

Non-Goals

• We are not deciding here to adopt NI’s year-based majoring; that remains an open question.

Proposal

1. Versioning rules

   • Major: bump only when LabVIEW introduces a breaking API change that requires us to break compatibility.
   • Minor: backward-compatible features.
   • Patch: backward-compatible bug fixes.
   • (Optional) Attach build metadata (e.g., +build.<shortSHA> or CI run number) on pre-release/CI artifacts for traceability.

2. Fork compatibility

   • Forks should follow the same SemVer rules.
   • A Major in a fork signals an intentional break from upstream; Minors/Patches remain compatible within the same Major.
   • Document a simple compatibility matrix so users can compare upstream vX.Y.Z vs. fork vA.B.C at a glance.

3. Documentation

   • Add a VERSIONING.md describing the above and how LabVIEW changes map to our Major.
   • Add a FORKS.md (or a section within VERSIONING.md) explaining the fork compatibility policy & comparison guidance.

Acceptance Criteria

• VERSIONING.md added with: Major=LabVIEW breaking; Minor=feature; Patch=fix; examples included.
• FORKS.md (or section) added with guidance on using SemVer to signal fork breakage and a sample compatibility matrix.
• CI attaches build metadata to non-release artifacts for commit-level traceability (does not alter SemVer precedence).
• Release checklist updated to verify correct bump type before tagging/publishing.
• Project board/labels updated so reviewers can quickly validate the intended bump type during PR review.

Open Questions

• Should we mirror NI’s year-based Major (e.g., 2026.x.y) for outward-facing packages while keeping strict SemVer internally? (Decision deferred.)

Traceability (meeting source)

Tag	Source (verbatim context)
250807-009	Major bumps only if LabVIEW introduces breaking changes; otherwise stay on 1.x.y.
250807-007	Question whether to align with NI’s year-based majors vs. strict SemVer.

Requested labels: type: feature, area: release, semver, fork-compatibility, needs-decision (year-based-major)

[svelderrainruiz]

Having a major bump would trigger the expansion of a test plan, or additions to the test suite. Bumps to the other SemVer fields would trigger behaviors which can remain undefined. Undefined fields needs to be exposed on the "Compute Version" API" for white box testing.

[crossrulz]

A major bump could be caused by more than just LabVIEW breaking the API. We could change something that would break backwards compatibility, such as moving files, libraries, etc. or moving the Icon Editor API to a PPL. This should also cause a bump to the major version.

[crossrulz]

I'm against the mixing of internal and external versioning. Just keep it all the same, however the major version is defined.

[crossrulz]

If the main reason for the Semantic Versioning is easily telling compatibility, then year-based majors do not really make sense. Just because we are at a new year does not mean we broke compatibility. It just helps reinforce the age of the package. Not to say that is important information, but that is something that can easily be found through VIPM or a version history document. There is also the possibility we break compatibility twice in a given year (unlikely, but still possible).