devguide/conventions.rst

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.