Skip to content

Updating and Versioning Terms

The ANC Terms of Use are continuously adjusted to reflect evolving internal workflows, external requirements and legal frameworks. The entire handbook, including terms, is version-controlled with Git.

The main terms are the only explicitly versioned documents in the handbook, because their specific versions need to be referenced externally, for example the ANC License is linked in the datasets metadata. We use Git Tags with Semantic Versioning for Documents to mark and reference specific versions of the main terms.

Explanatory texts to main terms

Changes to the explanatory texts accompanying the main terms are made without Git Tag versioning — these texts are not part of the terms themselves.

Additional policies

Changes to the texts of additional policies are made without Git Tag versioning.

Versioning main terms

Each version of the main terms documents is tagged with a Git Tag. We use Semantic Versioning for Documents (MAJOR.MINOR.PATCH) for numbering the versions.

All tagged versions are listed in the Agreement history section of the terms index.

Tag naming convention:

  • Terms of Service: tos_MAJOR.MINOR.PATCH
  • Transfer and License Agreement: tla_MAJOR.MINOR.PATCH
  • ANC License: license_MAJOR.MINOR.PATCH

Working on a new version

Every change to a terms document must go through an issue and a merge request workflow - this enables review, prevents mistakes, and creates a clear diff between versions. The reason and nature of changes must be documented in the issue.

Multiple commits can usually be squashed. If changes differ in nature across documents, document them at minimum in commit messages.

Referencing between terms

Some terms documents reference others. Use the file name to reference the needed document. Do not use git tags for referencing terms. We want the rendered handbook to represent the newest document versions.

Workflow

  1. Document required changes in a new issue.
  2. Make all changes to the relevant terms in a merge request - enables immediate diff review in the MR.
  3. Create new tag for each changed main term document, for example, git tag -a tla_1.2.3 -m "Transfer and License Agreement 1.2.3.".
  4. Push local tags to the remote.
  5. Add new version tags, changes summary, and links to changes to Terms history.

Communicate the changes

Work in progress

Major changes to the terms should be communicated to the users. Moreover, if a newer ANC License should take effect, it has to be updated in the relevant datasets.

These two workflows need to be defined.

Useful commands

Create a tag: 

git tag -a <tag-name> -m "Tag message."

Delete a local tag: 

git tag -d <tag-name>

To delete a tag on the remote, use GitLab interface or: 

git push origin --delete <tag-name>

Push local tags to the remote: 

git push origin <tag-name>

Synchronise local tags after deleting them on the remote: 

git fetch --prune --prune-tags origin