Contributing#

This page describes the internal process for making changes to the standard repository.

Getting started#

Before contributing to Markdown pages, read the Common conventions.

Before authoring a new documentation page, or extensively editing an existing page, learn how to Edit documentation with Google Docs.

Before contributing to JSON Schema and CSV codelists, read the Schema style guide and the schema patterns section of ODS’ Standards Lab.

To get up to speed on OCDS standard development, you should be familiar with:

The standard itself
- OCDS documentation, in particular the schema and codelists
- Extension Explorer
The policies it follows

To improve your technical writing skills, consider taking Google’s Technical Writing Courses, which can be completed in a day.

Proposing changes#

For examples, see Add an example. For all other changes:

Agree on a proposal in a GitHub issue.
Assign the issue to yourself, and move the issue’s card to the In progress column.
Create a branch of the standard repo (not a branch of your fork) in which to make your changes.
- Never use normative words on guidance pages. Use non-normative synonyms instead.
- Consider composing Markdown content in Hemingway Editor or Grammarly, as suggested in the Common conventions.
- After adding a definition to release-schema.json, add a sub-heading for the new sub-schema in reference.md.
- After editing release-schema.json or meta-schema-patch.json, run:
```
python manage.py pre-commit
```
  One-time setup
  pip install -r requirements.txt
Update the changelog, maintaining schema order in the list of changes.
Commit your changes.

Atomic changes

Make atomic changes in one commit, rather than over many commits: for example, when adding a definition to the schema, add it to the schema reference documentation in the same commit. That way, reverting a commit doesn’t leave the standard in an incoherent state.
Commit messages

Use the following format for commit messages:
```
scope: Capitalized, <72 characters, no period

A longer description of paragraph text, as needed.
```
For example:
```
primer/releases_and_records: Use "JSON data" instead of "JSON text"
```
The scope is based on which files were changed:
- The changelog file: changelog
- One Markdown file (can include changes to example files): path/to/page, for example: primer/index
- Many Markdown files in a single section: path/to/section, for example: guidance/map
- One schema file (can include changes to reference pages): the name of the file without extension, for example: release-schema
Other, less-used scopes are:
- build: Changes to the build system (requirements files, include, script, Makefile, *.cfg, *.py)
- ci: Changes to continuous integration (.github/workflows)
- locale: Changes to translations (docs/locale)
- test: Changes to tests (tests)
- chore: Any other change not warranting a changelog entry (e.g. renaming pages or fixing typographical errors, broken URLs, Markdown syntax, etc.)
Most commits are made in pull requests, such that it’s easy to find the discussion on GitHub. As such, it’s not necessary to provide a long narrative, if it exists in a pull request or linked issue.

Reference:
Create a pull request.
- Reference the issue number in the pull requests’ description.
- Set the base branch, e.g. 1.2-dev for OCDS 1.2 or 1.1-dev for OCD 1.1.
- Set the milestone, e.g. 1.2.0 for OCDS 1.2.
Assign a data support manager to review.
- See the next section for reviewer’s instructions.
- If changes are requested, make the changes, then repeat this step.
Once approved by a data support manager, assign James to review.
- If changes are requested, make the changes, then repeat this step.
Once approved by James, you can merge it yourself.

Logging changes#

Follow the Changelog style guide.
If a codelist is added, use the versionadded admonition to indicate the version in which it was added, in codelists.md.
If a code is added, use the versionchanged admonition to indicate the version in which it was added, with the message “Added the ‘newCode’ code.”, in codelists.md.

Note

If the codelist is open and frequently updated (like document type, milestone type, classification scheme, party role) or if it is external (like currency from ISO 4217), skip this step.
If a codelist is deprecated, use the deprecated admonition to indicate the version in which it was deprecated, in codelists.md.
If a code is deprecated, use the deprecated admonition to indicate the version in which it was deprecated, with the message “Deprecated the ‘oldCode’ code.”, in codelists.md.
If a field is added to the release schema, unless it is a major structural change like the parties array, don’t add any admonition to reference.md.
If a field is deprecated in the release schema, and if it has its own section in reference.md, use the deprecated admonition to indicate the version in which it was deprecated.

Reviewing changes#

You can use this feature to suggest changes directly.

You should check for:

Correctness: Do the changes conform to the standard and its principles?
Style: Do the changes respect the Common conventions and Schema style guide? Are normative words used on guidance pages?
Spelling and grammar: If there are few errors, suggest changes directly. If there are many errors, ask the author to use Grammarly or similar.

Repository management#

Issues#

All issues should be assigned one or more labels.

Milestones#

Each development version should have a milestone, like 1.1.5, 1.2.0 or 2.0.0. There should at most one milestone for each of the patch, minor and major levels.
All issues should be assigned a milestone, unless they have the label Focus - Extensions or Extensions - Local.
Issues labelled Extensions - Drafted should be assigned the Extension Explorer milestone, unless they have the label Extensions - Local.
Non-normative issues should be assigned either the Examples or Iterative improvements milestone.

Projects#

Each development version under active development should have a organization-wide project using the Automated kanban with reviews template and linked to the standard, ocds-extensions and extension-explorer repositories.

Modelling approaches#

Before proposing new structures:

Draft a JSON example with reasonable values
Check other standards for potential models

Architecture decision records: