A set of stylistic rules used to classify our software repositories into one of a number of development stages. The rules are structured to create a number of numerical stages that we consider represent traits of software repositories that exhibit a pattern of increasing 'product quality'.
Background
We have a lot of software repositories and need to guide each of them so that we converge on a common set of rules that represent best practices in software development.
It is natual, at the start of its life, for code to start as a 'rough and ready' implementation of a rapidly emerging design or concept. During this 'pioneering' step initial implementations often avoid introducing too many processes and tools as the trailblazing effort is usually hampered and 'bogged-down', with efforts distracted by unnecessary rules. In the early days too many 'quality' rules waste valuable development time when your code is evolving rapidly where features appear and disappear quickly. At this stage, development practices benefit from being deliberately relaxed.
At some stage in the lifetime of the code it becomes valuable and the desire to control its behaviour becomes as important (or more important) that enhancing it. It's at this stage, if you've left them out, you might be thinking of code formatters, test frameworks, change-log, continuous integration, and deployment and delivery options.
Rather than switch directly from the prototyping stage to a top-heavy process that represents the 'ultimate' in assured quality in one step the stages we describe here allow you to adopt the rules you need onm a 'sliding scale' to allow gradual migration. And we have a lot of repositories to consider.
The rules defined here are designed to promote consistency across diverse repositories where developers may use employ different languages and tools. The rules focus on a generic set of processes that should be compatible with any software application. The rules help the observer and developer understand how the software is documented, written, tested, built and delivered.
DOCUMENT UNDER REVIEW
We have defined policies for four development stages, numbered 0 to 3. The higher the stage number, the more demanding the policy.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
Repositories at Stage 0 are the weakest in terms of policies. They are repositories that represent new or legacy code that is yet to be promoted to a higher stage.
For agility the policy demands for Stage 0 are deliberately weak.
- The repository SHOULD have a README file in the root of the repository
- The root README format SHOULD be one of Markdown (
.md) or ReStructured Text (.rst) - The repository SHOULD display our "Policy Stage 0" badge in the README
Stage Summary: In order to understand how to contribute to or use a "Stage 0" repository you are likely to need to talk to the author. Process is weak, inconsistent and the build, test and delivery may be unclear
Use the badge in your project's README.md:
[](https://github.com/InformaticsMatters/code-repository-development-stages)Use the badge in your project's README.rst:
.. image:: https://img.shields.io/badge/dev%20stage-☆☆☆%20%280%29-000000?labelColor=dc332e
:target: https://github.com/InformaticsMatters/code-repository-development-stages
Which looks like this:
Repositories that have no badge SHOULD be considered "Stage 0" repositories.
- The repository MUST adopt our [Conventional Commit] message policy
- Automated validation of the commit message MUST be implemented.
This will normally be achieved using git's pre-commit hooks, which can be
automatically configured using pre-commit and its corresponding
.pre-commit-config.yamlfile - The repository MUST have a README file in the root of the repository
- The repository MUST clearly identify the repository build artefacts, i.e. what gets built (i.e. a container image). Users MUST expect to find a Building section in the README that contains instructions for building and publishing the artefacts 5 The repository MUST display our "Policy Stage: 1" badge in the README
Stage Summary: Commit messages conform to a standard, are enforced automatically, and it will be clear what the repository's artefacts are and how to build them and find them
Use the badge in your project's README.md:
[](https://github.com/InformaticsMatters/code-repository-development-stages)Use the badge in your project's README.rst:
.. image:: https://img.shields.io/badge/dev%20stage-★☆☆%20%281%29-000000?labelColor=dc332e
:target: https://github.com/InformaticsMatters/code-repository-development-stages
Which looks like this:
- The repository MUST satisfy all the policies defined in "Stage 1"
- The repository MUST employ CI/CD to build and publish the repo's artefacts
For GitHub this will be the use of Actions located in the repository's
.github/workflowsdirectory. For GitLab this will be the use of agithub-ci.ymlscript - The repository MUST document a branch policy
- Software releases MUST be identified using a release (GitHub) or a tag (GitLab or GitHub)
- Release numbers MUST us semantic versioning, and we typically support
3-digit (
1.0.0) and 2-digit (2022.1) styles, including pre-release conventions that introduce suffixes like-rc.1 - The repository SHOULD declare a code style guide
- The repository SHOULD contain and automatically run Unit tests
Stage Summary: Commit messages conform to a standard, are enforced automatically, repository artefacts are built automatically and development contributions using branches and release mechanisms will be clear
Use the badge in your project's README.md:
[](https://github.com/InformaticsMatters/code-repository-development-stages)Use the badge in your project's README.rst:
.. image:: https://img.shields.io/badge/dev%20stage-★★☆%20%282%29-000000?labelColor=dc332e
:target: https://github.com/InformaticsMatters/code-repository-development-stages
Which looks like this:
- The repository MUST satisfy all the policies defined in "Stage 2"
- The repository MUST contain a CHANGELOG that is constructed automatically from the content of commit messages. If you use Commitizen as a tool to generate the CHANGELOG our .cz.yaml configuration file will be of value - it recognizes the commit message types and structures the CHANGELOG sections accordingly
- The CHANGELOG content MUST contain details of every commit, regardless of whether the change alters the code's behaviour. For example, documentation and test changes must be present in the CHANGELOG file.
- The repository MUST declare a code style and the repository SHOULD enforce the code style
- The repository MUST automatically run linting tools that are recognised by the community for the significant languages present in the repository. For example, if a repository contains Java and YAML, the observer can expect to find linters for these language files.
- The repository MUST contain clear instructions on how to use the artefacts i.e. it must have a guide for deploying and using the artefacts
- The repository SHOULD publish unit-test coverage statistics
- The repository SHOULD contain and automatically run Functional tests
Summary: A strict set of policy rules. Commit messages and code style conform to a standard, and are enforced automatically. Code is built and can be deployed automatically. Users will clearly understand what is built, how it's built, how it's delivered, and what changes have been made
Use the badge in your project's README.md:
[](https://github.com/InformaticsMatters/code-repository-development-stages)Use the badge in your project's README.rst:
.. image:: https://img.shields.io/badge/dev%20stage-★★★%20%283%29-000000?labelColor=dc332e
:target: https://github.com/InformaticsMatters/code-repository-development-stages
Which looks like this:
- Our Conventional Commit style guide
- Commitizen .cz.yaml configuration