Standard for Public Code

Contents

  1. Requirements
  2. How to test
  3. Public policy makers: what you need to do
  4. Managers: what you need to do
  5. Developers and designers: what you need to do
  6. Further reading

Contribute on GitHub

Document codebase maturity

Clearly signalling a codebase’s maturity helps others decide whether to use and contribute to it. A codebase version’s maturity includes the maturity of its dependencies. Understanding how a codebase has evolved is key to understanding the codebase and how to contribute to it.

Requirements

  • The codebase MUST be versioned.
  • The codebase MUST prominently document whether or not there are versions of the codebase that are ready to use.
  • Codebase versions that are ready to use MUST only depend on versions of other codebases that are also ready to use.
  • The codebase SHOULD contain a log of changes from version to version, for example in the CHANGELOG.
  • The method for assigning version identifiers SHOULD be documented.
  • It is OPTIONAL to use semantic versioning.

How to test

  • Confirm that the codebase has a strategy for versioning which is documented.
  • Confirm that it is obvious to policy makers, managers, developers and designers whether the codebase has versions that are ready to use.
  • Confirm that ready to use versions of the codebase do not depend on any versions of other codebases that are not ready to use.
  • Check that the versioning scheme of the codebase is documented and followed.
  • Check that there is a log of changes.

Public policy makers: what you need to do

  • When developing policy, understand that any source code developed needs to be tested and improved before it can be put into service.
  • Consider versioning policy changes, especially when they trigger new versions of the source code.

Managers: what you need to do

  • Make sure that services only rely on versions of codebases of equal or greater maturity than the service. For example, don’t use a beta version of a codebase in a production service.

Developers and designers: what you need to do

  • Make sure that the codebase versioning approach is followed for all releases.

Further reading