https://github.com/informaticsmatters/code-repository-development-stages
https://github.com/informaticsmatters/code-repository-development-stages
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/informaticsmatters/code-repository-development-stages
- Owner: InformaticsMatters
- Created: 2022-04-12T11:09:46.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2022-04-23T07:39:53.000Z (about 4 years ago)
- Last Synced: 2025-01-25T18:43:22.467Z (over 1 year ago)
- Size: 28.3 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Code Repository Development Stages
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.
# 2022.1-alpha.1 Rules
**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]._
## Stage 0
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.
1. The repository **SHOULD** have a README file in the root of the repository
2. The root README format **SHOULD** be one of Markdown (`.md`)
or ReStructured Text (`.rst`)
3. 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`:
```md
[](https://github.com/InformaticsMatters/code-repository-development-stages)
```
Use the badge in your project's `README.rst`:
```doctest
.. 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.
## Stage 1
1. The repository **MUST** adopt our [Conventional Commit] message policy
2. 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.yaml` file
3. The repository **MUST** have a README file in the root of the repository
4. 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`:
```md
[](https://github.com/InformaticsMatters/code-repository-development-stages)
```
Use the badge in your project's `README.rst`:
```doctest
.. 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:
## Stage 2
1. The repository **MUST** satisfy all the policies defined in "Stage 1"
2. 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/workflows` directory. For GitLab this will be the use
of a `github-ci.yml` script
3. The repository **MUST** document a branch policy
4. Software releases **MUST** be identified using a release (GitHub) or
a tag (GitLab or GitHub)
5. 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`
6. The repository **SHOULD** declare a code style guide
7. 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`:
```md
[](https://github.com/InformaticsMatters/code-repository-development-stages)
```
Use the badge in your project's `README.rst`:
```doctest
.. 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:
## Stage 3
1. The repository **MUST** satisfy all the policies defined in "Stage 2"
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
3. 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.
4. The repository **MUST** declare a code style and the repository **SHOULD**
enforce the code style
5. 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.
6. 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
7. The repository **SHOULD** publish unit-test coverage statistics
8. 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`:
```md
[](https://github.com/InformaticsMatters/code-repository-development-stages)
```
Use the badge in your project's `README.rst`:
```doctest
.. 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:
## References
- Our [Conventional Commit style guide]
- Commitizen [.cz.yaml] configuration
## Illustrative repositories
- [data-manager-job-operator]
---
[.cz.yaml]: https://gist.github.com/alanbchristie/19077203307101e9e9d52086488d4921
[commitizen]: https://pypi.org/project/commitizen
[conventional commit style guide]: https://discourse.squonk.it/t/conventional-commit-style-guide
[data-manager-job-operator]: https://github.com/InformaticsMatters/data-manager-job-operator
[functional tests]: https://en.wikipedia.org/wiki/Functional_testing
[pre-commit]: https://pre-commit.com
[rfc 2119]: https://www.ietf.org/rfc/rfc2119.txt
[unit tests]: https://en.wikipedia.org/wiki/Unit_testing