Governance · governance/VERSIONING.md
Versioning
How Tórculo is numbered, how each part writes its version inside its files, what each kind of version may change, and how the conformance suite and the libraries are versioned on their own. The normative rules are in SPEC §22; this document repeats them and adds the policy around them. The key words MUST, SHOULD and MAY are to be read as described in BCP 14 (RFC 2119 and RFC 8174) when, and only when, they appear in capitals.
The specification
The specification is numbered MAJOR.MINOR, with editorial releases as a third number.
| Kind | Example | May change | Needs |
|---|---|---|---|
| Major | 1.0 → 2.0 | anything, including breaking changes, with the legacy rules below | RFCs |
| Minor | 1.0 → 1.1 | only additions that conforming products of 1.0 can ignore, and new epochs of the language | RFCs |
| Editorial | 1.0.0 → 1.0.1 | wording, examples, translations, corrections that change no behaviour | no RFC |
Releases are tagged spec-vMAJOR.MINOR.PATCH (the first is spec-v1.0.0), separately
from the libraries. Each published text states its maturity: working draft (stable
enough to implement, open to change by RFC; Tórculo 1.0 has been one since 2026-10-15) or
final (every RFC it contains is implemented by two independent implementations and the
suite covers every testable MUST).
The version inside each file
| Part | Where the version is written | Tórculo 1.0 |
|---|---|---|
| Pliego language | MESA v<epoch> in the preamble (optional) | epoch 2 |
| Portable project | MANIFIESTO.json → formato | mesapack 1 |
| Pieces | the card's nivel and the contract version | 1 |
| Canon | canon.toml → version, copied to every generated file | 1 |
| Láminas | signature LAMINA\0\x01 and manifiesto.json → version | 1 |
| Materias | the convention (group 0 and Plano, 96 bytes) | 1 |
| Takes | START → version | 0x8000_0002 (reads 0x8000_0001) |
The language: epochs
- The constitution: a pliego that compiled once compiles always. A compiler that claims an epoch compiles every pliego of that epoch and of the earlier ones it claims.
- An epoch's vocabulary is frozen, reserved words included. A new epoch may add words, lines and profiles; it may not change the meaning of a valid pliego of an earlier epoch.
- A word can only be retired by a new epoch that declares it legacy; pliegos that declare the older epoch keep it.
- Epoch 1 (
SPEC-MESA.mdof manim-saorín) is legacy: compilers SHOULD read it.
The other parts
mesapack: a new major is a new format; a minor (mesapack 1.1) only adds members.- Láminas: a new layout is version 2, with its own signature byte.
- Takes: the fork's range starts at
0x8000_0000; every layout or opcode change takes the next version, and readers keep reading the versions this standard lists. - Canon: any change of value bumps
version; additions of keys too. - Materias: the convention changes only with a major version of the specification.
Deprecation
A feature is deprecated by RFC, marked as such in the specification with the version that deprecated it, and removed no earlier than the next major version and at least 24 months later. Reserved words never expire within their epoch.
The conformance suite
The suite (conformance/manifest.json) is versioned on its own, MAJOR.MINOR.PATCH:
a patch fixes a wrong case, a minor adds cases, a major follows a major of the
specification. Every report names the suite version and its cases_sha256. Pending
cases (known deviations of the reference implementation, SPEC Appendix D) are reported
apart and do not count as passed or failed.
Implementations and packages
Libraries and tools have their own semantic versions, starting at 0.x until Tórculo 1.0
is final and the parts they implement have two independent implementations. The reference
implementation of the language reports its epoch (MESA v2 beta) and its version
(1.0.0b1).