Contributing

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

Getting started

Before contributing to Markdown pages, read the markdown style guide.

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

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

• The standard itself

  • OFDS documentation

• The policies it follows

  • Semantic versioning

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

Proposing changes

1. Agree on a proposal in a GitHub issue.

2. Assign the issue to yourself, and move the issue’s card to the In progress column.

3. Create a branch of the open-fibre-data-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 schema.json, add a sub-heading for the new sub-schema in reference.md.

4. Update the changelog, maintaining schema order in the list of changes.

5. Run ./manage.py pre-commit to update the reference documentation

6. If you used a validation keyword, type or format that is not already used in the schema:

7. Update the list of validation keywords, types or formats in JSON Schema usage.

8. Add a field that fails validation against the new keyword, type or format to network-package-invalid.json.

9. Check that OFDS CoVE reports an appropriate validation error.

10. If you added a normative rule that is not encoded in JSON Schema:

11. Update the list of other normative rules.

12. Add a field that does not conform to the rule to network-package-additional-checks.json/

13. Open a new issue to add an additional check to Lib Cove OFDS.

14. 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/index: 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

• One schema file (can include changes to reference pages): the name of the file without extension, for example: 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:

• Angular Commit Message Format

• Conventional Commits

• Write joyous git commit messages

1. Create a pull request.

   • Write the pull requests’ description, filling in the relevant bits of the provided template.

   • Set the base branch, e.g. main.

   • Set the milestone, e.g. 1.0.

2. Assign to another team member to review.

   • See the next section for reviewer’s instructions.

   • If changes are requested, make the changes, then repeat this step.

3. Once approved, you can merge it yourself.

Logging changes

1. Follow the changelog style guide.

Reviewing changes

You can use GitHub’s suggestions 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 style guides? 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 alpha or beta. There should at most one milestone for each of the patch, minor and major levels.

• All issues should be assigned to a milestone.

Projects

• Each version under active development should have a organisation-wide project.

Modelling approaches

Before proposing new structures:

1. Draft a JSON example with reasonable values

2. Check other standards for potential models