Development Conventions

ONF has many (over 300) software repositories as of 2022, and to effectively develop across all of these projects, the following development conventions are used.

Strategy

The general strategy for ONF software development is as follows:

Make it easy to start contributing to any repo

A convention we’ve embraced in nearly all repos is to have a Makefile in their base directory, which has a few common targets:

  • make help: Get a list of make targets

  • make build run

  • make test run all tests, as they’d be run in CI by a

Most Makefiles use the GNU Make syntax variant.

Automated tests should be identical for the developer and automation

The CI test runner (Jenkins or similar) that performs automated testing should run the same tests in the same way that a developer would on their local system, by running make test. There should be no (or very rare) cases where a test will pass locally but fail in CI.

Additionally, this greatly simplifies the configuration of the test runner - it only needs to run make test. In some cases, it may be necessary for the Makefile to include commands that generate Jenkins-consumable output, such as test results (usually in JUnit, xUnit, or TAP formats) or coverage information (usually in Cobertura XML format).

Style, formatting, linting, license compliance should be automated

Code review should be about the structure and design of the code, and should

To that end, automated tools should be used that verify and conform the code to a specific convention and standard:

  • Formatting tools such as go fmt, black and similar should be used to conform code to style guidelines

  • Linting tools such as pylint, yamllint

In the documentation space, spelling and other checks should also be performed.

Versioning and Releasing Software

Versioning software and performing releases are fundamentally for two audiences:

  1. Providing compatibility claims about

  2. Developers who use the

Two common and recommended versioning schemes are;

  • SemVer

  • CalVer

Division of responsibilities

Automated tools should perform low-level versioning tasks like creating tags on repos.