TODS Versioning and Change Management Policy ¶

Tip

When capitalized in this document, the words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” refer to their respective definitions in RFC 2119.

Definitions ¶

Tip

Definitions of various roles such as TODS Board, TODS Manager, and TODS Contributors refer to their respective definitions in the TODS Governance.

The following definitions build on the overall TODS Governance definitions and exist within the purpose of the TODS Versioning and Change Management Policy.

TODS Release ¶

An official version of the TODS Specification which can be referenced in perpetuity by a version number. The process by which a new release is made and determination of a version number is discussed below.

Each change to normative content in the main branch of the TODS Repository MUST be considered a new release and assigned a version number.

Normative Content ¶

Normative Content is the prescriptive part of a standard. It sets the rules to be followed in order to be evaluated as compliant with the standard, and from which no deviation is permitted.

Non-Normative Content ¶

Non-normative content is the non-prescriptive, or ‘descriptive’, part of a standard. This may include analogies, synonyms, explanations, illustrations, context, and examples. In the event non-normative content contradicts normative content, the normative content is to be followed.

Issue Working Group ¶

Tasked by the TODS Manager with resolving a specific issue with respect to the TODS Specification.

Urgent Needs ¶

Urgent needs MUST pose significant risks to security, compliance, or the operational integrity of stakeholder systems. These MAY include necessary revisions due to legal mandates, critical security vulnerabilities, or severe technical inaccuracies that directly impair system functionalities. Urgent needs SHOULD necessitate an implementation timeline which is inconsistent with the normal change-making process.

Change-Making Process ¶

This change-making process covers all normative content changes to the TODS Specification and occurs in the following stages:

Stage	When	Who (led by)
Need Identification	Anytime	Anyone
Need Prioritization	Quarterly	Contributors (TODS Manager)
Initial Proposal Development	Prioritized quarter	Issue Working Group (TODS Managerr)
Contributor Review + Adoption	Pull request for proposed change submitted after consensus in the Working Group	Issue Working Group (TODS Manager)
Implementation	When decision made to consensus achieved on proposal	Issue Working Group (TODS Manager)
Released	Next quarterly release	TODS Manager

Each of these stages is discussed in more detail below.

Need Identification ¶

Initiated when Any TODS Contributor identifies a need that should be addressed in the TODS Specification.

Actions:

An TODS Contributor submits an issue to the TODS Repository which identifies the need that they would like addressed and a rough assessment of its addressable audience.
An TODS Manager triages issue and asks for more detail from the Contributor if needed.
An TODS Manager determines if issue resolution would require a normative change.

Resolution: TODS Manager puts issue into consideration for next quarterly issue prioritization

Prioritization ¶

Initiated when the TODS Manager starts a development cycle after or near the end of a quarterly release.

Actions:

TODS Manager to solicit feedback from TODS Contributors on which needs to prioritize.
TODS Manager to propose a set of needs that the community will focus on resolving based on feedback and available community capacity.
TODS Board will approve a set of needs to focus on based on TODS Manager’s proposal and TODS Contributors’ feedback.

Resolution: TODS Manager will create a Milestone for the next release in the TODS Repository and fill it with the issues the TODS Board prioritized.

Initial Proposal Development ¶

Initiated [for each need] when TODS Manager, in consultation with the TODS Board and TODS Contributors, convenes an Issue Working Group to address a prioritized issue or set of interrelated issues.

Actions:

TODS Manager convenes an Issue Working Group to develop a resolution to the issue. Working Group members document discussion points about approach in the relevant github issue.
While consensus will be sought, if the Issue Working Group members cannot come to a unanimous agreement about the solution, the TODS Manager may ask the TODS Board to make a decision after hearing feedback from various perspectives.
Issue Working Group members update the schema and documentation according to the proposal on a feature branch.

Resolution: Issue Working Group submits a pull request to the develop branch.

Contributor Review + Adoption ¶

Initiated [for each need] when: TODS Manager invites TODS Stakeholders outside of the Working Group to review and comment on the proposal

Actions:

The TODS Manager MUST invite people outside of the Working Group to review and comment on the proposal for a minimum of two weeks, making sure TODS Contributors with different roles and backgrounds have had a chance to consider it.
The TODS Manager MUST review the proposal for consistency with the Open Standards definition maintained by the Mobility Data Interoperability Principles.
The TODS Manager MUST offer tools, services and assistance to any TODS Contributor who is unable to fluidly interact with the tooling used in the review process.
A minimum of three TODS Contributors outside the Working Group MUST publicly comment on each proposal for it to move forward and indicate a score of:
- Accepted;
- Accepted with minor changes; or
- Substantially revised.
If 100% of reviewers accept, the proposal is adopted without need for further discussion.
If any reviewer accepts with minor changes, the suggested change must be considered by the Working Group.
If the Working Group decides to incorporate the edited proposal will be re-circulated for some period time greater than 72 hours and previous reviewers notified. If nobody objects to the change in that time, it is adopted.
If the Working Group does not agree with the suggested change, they may appeal to the TODS Boardto make a final decision about its necessity.
If any reviewer requests substantial changes, they must also agree to work with the working group on developing an alternative solution to the need.
If the working group believes the substantial change request is invalid or without merit, they may appeal to the TODS Board to make a final decision about if revisions are necessary.

Resolution: Change as represented in the pull request from the feature branch is approved and merged into the develop branch.

Full Implementation ¶

Initiated [for each need] when: Final change proposal is approved - although initial work can begin ahead of this.

Actions:

TODS Manager MUST ensure the relevant accompanying documentation fleshed out.
TODS Manager MUST ensure Changelog fully documented.
TODS Manager MUST ensure sample datasets updated or added that support the new feature.
TODS Manager MUST ensure any relevant updates to continuous integration and testing are completed.
TODS Manager MAY make any number of pre-release(s).
TODS Manager MUST identify and ensure resolution of relevant conflicts among proposals as overseen by the TODS Board or their designee.

Resolution: Requirements for release are met.

Release ¶

Initiated: On a quarterly schedule maintained by the TODS Manager.

Actions: See Release Management.

Expedited Change Management ¶

This section outlines an expedited process for implementing changes in response to urgent needs which are critical to maintaining the security, compliance, or operational functionality of TODS Specification balancing rapid response with informed, transparent decision-making.

Process ¶

Identification: Stakeholders SHOULD promptly report urgent needs to the TODS Manager, detailing the problem and its potential impact.
Rapid Evaluation: The TODS Manager MUST convene a group of at least 2 TODS Contributors of their choosing to swiftly assess the issue’s urgency and validity.
- If it meets their threshold for an urgent need, they forward a list of their proposed Urgent Working Group Members to the TODS Board.
- The Urgent Working Group Members SHOULD contain representatives of TODS Contributors affected stakeholder groups.
- The Urgent Working Group size SHOULD be at least three and reflect the scale of the problem and also need for agile decision making.
- The TODS Board MAY object to their characterization of the need as urgent.
- The TODS Board MAY make changes to the Urgent Working Group members.
- If the TODS Board fails to respond within 48 hours, the Urgent Working Group MAY proceed with their implicit approval.
Solution Identification: The Urgent Working Group, managed by the TODS Manager, MUST identify a solution that meets the urgent need and document it as a PR to the main branch of the TODS Repository – outside the normal release cycle.
Decision-Making: A supermajority (two-thirds) of the Urgent Working Group members MUST approve the proposed change to meet the urgent need. If the decision is deadlocked, the decision is escalated to the TODS Board.
Implementation: The rest of the implementation and release cycle mirrors the main change-making process.

Versions and Release Management ¶

Releases ¶

Each change to normative content in the main branch of the TODS Repository MUST be considered a new release and assigned a version number.

Each release MUST contain one or more changes to normative content which have been approved through the change-making process.
Each release MUST be reviewed and approved in the TODS Repository by 2+ members of the TODS Board – or their designees – for accuracy and consistency with the intent of the change.
Each release MUST be tagged with its version number.
Each release MUST have documentation available.
Each release MUST have an entry in `CHANGELOG.md``.
Each release MUST be specified as a release on Github.
Each release MUST be noticed to any TODS mailing lists or discussion groups.
Each release SHOULD have sample datasets (real or exemplary) which cover the normative changes in the release.

Pre-releases ¶

Each approved change to normative content in the develop branch of the TODS Repository MAY be considered a pre-release and assigned a pre-release version number.

Pre-releases MAY be made in order to evaluate and work on incrementally-approved changes.

Each pre-release MUST contain one or more changes to normative content which have been approved through the change-making process.
Each pre-release MUST be reviewed and approved in GitHub by 1+ members of the TODS Board – or their designees – for accuracy and consistency with the changes’ intent.
Pre-releases MUST be tagged with an appropriate pre-release version number:
Pre-releases that have incorporated all the normative changes for the target-release MUST have a beta version number;
otherwise, they MUST receive an alpha version number.
Each pre-release MUST have documentation available.
Each pre-release MUST have an entry in `CHANGELOG.md``.
Each pre-release MAY be specified as a pre-release on Github.

Release Schedule ¶

Barring significant unexpected events:

Major releases SHOULD be limited to no more than once per year;
Minor releases MAY be expected approximately quarterl .

Version Numbering ¶

TODS Releases MUST be reflected by an incremental version number based on a semantic versioning policy as detailed below.

Release versions MUST be named with incremental increases to the format <MAJOR>.<MINOR> where:
Major versions reflect backwards-incompatible changes
Minor versions change the normative content in a way that is backwards-compatible

Pre-release versions MUST be named with the <MAJOR>.<MINOR> of their target release name and appended with either: -alpha.<NUMBER> where NUMBER starts at 1 and increases by 1 for each alpha release of that target release. -beta.<NUMBER> where NUMBER starts at 1 and increases by 1 for each beta release of that target release.

Non-normative changes MUST NOT increment the TODS Version Number even though they are represented by updates in the main branch of the TODS Repository.