Standard repository

Branches and tags

The standard uses semantic versioning, with versions following the MAJOR.MINOR.PATCH name convention.

Each minor version of the standard’s documentation is built from a “live” branch named after the version, like 1.0. For each live branch, there is a dev branch with a -dev suffix. Patch versions may further branch off the dev branch, with work merged into the dev branch before finally being merged into the live branch. standard.open-contracting.org redirects to (https://standard.open-contracting.org/latest/en/), which symlinks to the most recent live branch; this makes it possible to link to the current version of the documentation without specifying the version number.

Sample branch structure:

• 1.0: contains the deployed version of OCDS 1.0

• 1.1: contains the deployed version of OCDS 1.1

  • 1.1-dev: used to stage changes to version 1.1 (such as minor documentation changes)

  • 1.1.1-dev: used to isolate work on version 1.1.1 (including schema changes and fixes)

The X.X and X.X-dev branches are protected. The standard repository also protects non-existent infrastructure and profiles branches. These names match sub-directories on the server, and therefore must not be used for branches.

The published documentation has versions on different MAJOR.MINOR branches (e.g. https://standard.open-contracting.org/1.0/en/), whereas the published schema has versions on different MAJOR__MINOR__PATCH tagged releases (e.g. https://standard.open-contracting.org/schema/1__0__1/release-schema.json). This use of branches and tags allows documentation to change between versions, while ensuring schema isn’t changed between versions.

Structure

• .tx/config: configuration of Transifex

• include/: common makefiles for building documentation

• assets/: images used in the documentation

• docs/: English documentation

  • *.md */*.md: English documentation text

  • conf.py: Sphinx configuration

  • _static/: CSS and JavaScript for the documentation

  • _templates/: Jinja templates for the documentation (see Changing the theme)

  • locale/: translations of the English documentation

• schema/: schema-related files

  • *.json: JSON Schema files

  • codelists/: codelist CSV files

  • tests/: Python tests of the JSON Schema files

• tests/: Python tests of the built documentation

The following files are created by running a build and are not version controlled:

• .ve/: Python virtualenv, containing all dependencies

• build/: contains the built copy of the documentation website

To understand babel_ocds_codelist.cfg and babel_ocds_schema.cfg, see Understanding Transifex.