Policy Advisory  Digital Policy Version Numbers

Date:	07/30/2021
Organization:	Executive Office of Technology Services and Security
Referenced Sources:	Website Domain Policy

Versioning numbers are used to identify what changes have been made when a page, document, code, database or other item is updated. This document explains how to interpret these numbers using standard semantic versioning, which is used in the EOTSS digital policies and guidelines.

Semantic versioning for policy

Versions include three numbers separated by two decimals, like this: X.X.X. Each X represents the number of times a change has been made to a policy, and what kind of change was made. In order, they stand for MAJOR.MINOR.FIX. 

Given a version number MAJOR.MINOR.FIX, increase the:

• MAJOR version number when you make changes that are incompatible with previous versions, or which dramatically change the obligations or responsibilities of an organization using this policy. A major change resets the numbers for both minor and fix changes. 
• MINOR version number when you add detail in a backwards-compatible manner. These changes may add or acknowledge new technologies, circumstances, or definitions, but don't require new actions or create new obligations. A minor change resets the number for fix changes, but does not affect the major number. 
• FIX version number when you make backwards-compatible fixes. These changes fix typos or improve clarity. They do not add anything new to the policy. A fix change does not affect the major or minor numbers. 

Here are some examples of how versioning might look for a policy

• When a policy is first posted publicly, it should be numbered as 1.0.0.
• If typos are found in that version and corrected, this new version becomes 1.0.1. 
• If the policy includes a list of acceptable file formats and the policy holders decide to add two new formats to that list, the new version becomes 1.1.0. 
• If the policy holders add to the definition of a certain term--not clarifying the original meaning, but adding to it--the new version becomes 1.2.0. 
• If the policy holders decide that anyone adhering to the policy must now change their workflow to have their work approved by another specific organization or office, the new version becomes 2.0.0. 

 

Additional explanation:

• Versions include three numbers separated by two decimals, like this: X.X.X. (For example: 1.0.0, 10.9.2, etc.)
• Fix revisions are indicated by incrementing the number following the second decimal, for example, the “3” in version number “1.2.3”. Fix revisions will not make substantive changes to the policy. These revisions intend to fix typos and improve clarity. Fix changes do not require any new action or create any new allowances.
• Minor revisions are indicated by incrementing the number following the first decimal, for example, the “2” in version number “1.2.3”. Minor revisions change the meaning of the policy to acknowledge additional circumstances, technologies, and allowances. Minor changes do not require any new action or create any new obligations for web applications already in compliance with the latest version of the policy.
• Major revisions are indicated by incrementing the first number, for example, the “1” in version number “1.2.3”. Major revisions change the policy in ways that may require action or create new obligations for organizations already in compliance with the latest policy.

Zero versions (0.x.x)

• A "zero version" is used for a draft version that has not been widely released to the users. For example, a new computer program that is still being built and tested. 
• Usually, when the draft is ready for release to its users for the first time, that becomes version 1.0.0. 
• For Mass.gov, working drafts of forthcoming policies or guidelines begin as a zero version before being published. For example, 0.2.1.
• Versions beginning with 0 are considered unstable and may include significant changes before 1.0.0 comes out.

Best practices

• A policy that refers to another policy should reference the version number of the second policy. 

For example, if EOTSS refers to a policy kept by the EOE, the EOTSS policy should point to the specific version of the EOE policy in the text of their own policy. "In accordance with the EOE Education Policy (version 1.3.2)..."