Versioning Policy
Methodology versioning guidelines — SemVer conventions for frameworks and applications.
Last updated on
SemVer conventions
All digital MRV (dMRV) methodologies in the Carrot Network follow Semantic Versioning (SemVer) to communicate the nature and impact of changes:
| Level | Meaning | Example |
|---|---|---|
| MAJOR | Breaking changes to verification logic that may affect existing integrations or alter rule outcomes | v1.0.0 → v2.0.0 |
| MINOR | New rules added or non-breaking enhancements to existing rules | v1.0.0 → v1.1.0 |
| PATCH | Bug fixes, documentation updates, or minor corrections that do not change rule behavior | v1.0.0 → v1.0.1 |
Framework versioning
Methodology Verification Framework (MvF) documents are versioned independently. Each version represents a specific state of the verification specification:
- MAJOR changes require a new framework version and may include a migration guide for Network Integrators whose data submission patterns need to adapt.
- MINOR changes add new verification requirements without altering existing ones.
- PATCH changes clarify ambiguous specifications or correct documentation.
Application versioning
Methodology Verification Application (MvA) releases track the MvF's MAJOR version to maintain alignment between specification and implementation:
- A new MvF MAJOR version triggers a new MvA MAJOR version.
- New rule implementations within the same MvF MAJOR version are MvA MINOR releases.
- Bug fixes in rule processors are MvA PATCH releases.
Version lifecycle
Each version passes through defined stages:
- Draft — Under development; not yet available for production use.
- Review — Under Community of Experts review; may change before publication.
- Published — Active in production; MassID documents are evaluated against this version.
- Deprecated — Superseded by a newer version; a grace period allows integrators to transition.
Transition policy
When a version is deprecated:
- Grace period — Network Integrators and supply chain participants are given advance notice to adapt to the new version.
- Existing credits — Credits issued under a deprecated version remain valid and tradeable. Deprecation does not retroactively affect previously verified claims.
- New submissions — After the grace period, new MassID submissions must conform to the current published version.
Update principles
All methodology updates are governed by three inviolable principles:
- Historical traceability preservation — No update may erase or make inaccessible a previous version. Outputs generated under a version must remain auditable under that version's rules. The ecosystem maintains a versioned repository with complete change history.
- Operational continuity — Updates must not cause abrupt interruption to active methodologies. When changes affect validation rules, calculations, or eligibility, a transition period allows coexistence.
- Transparent governance — Every change must be justified, documented, and communicated. Documentation records: what changed, why, who proposed, who approved, when it takes effect.
Alteration categories
| Category | Impact | Version increment | Approval |
|---|---|---|---|
| Minor corrections | No logic/calc/eligibility changes. Typos, formatting, references, wording clarifications. | PATCH | Internal curation with change record |
| Operational updates | Affect execution but not scientific basis. Adding/adjusting rules, refining eligibility, new events, metadata updates. | MINOR | Technical analysis by curation, Engineering consultation when MvA impacted |
| Substantive revisions | Modify calculation basis, key parameters, quantification logic, or fundamentals. | MAJOR | Full accreditation cycle |
Who can propose alterations
Changes can be proposed by: original MvF author, Operations & Methodologies team, Engineering team, independent VVBs, Community of Experts members. Each proposal must include: description, technical justification, expected impact, proposed category.
Version coexistence
When a new MvF version is published, the previous is not deactivated immediately. Both coexist during a transition period for MassIDs in transit.
The governing rule is entry version: each MassID is evaluated under the MvF version active at its first event (typically pick-up). New MassIDs after the effective date follow updated rules.
Typical transition periods: 30–90 days for operational updates, longer for substantive revisions (case by case).
Learn about the methodology lifecycle · Learn about the discontinuation policy