{"id":21721467,"url":"https://github.com/informaticsmatters/code-repository-development-stages","last_synced_at":"2026-01-04T09:06:21.427Z","repository":{"id":80604698,"uuid":"480774391","full_name":"InformaticsMatters/code-repository-development-stages","owner":"InformaticsMatters","description":null,"archived":false,"fork":false,"pushed_at":"2022-04-23T07:39:53.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-25T18:43:22.467Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/InformaticsMatters.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-12T11:09:46.000Z","updated_at":"2022-04-13T15:29:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"fd4b17bf-efd0-4933-8516-eded0f07f87f","html_url":"https://github.com/InformaticsMatters/code-repository-development-stages","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InformaticsMatters%2Fcode-repository-development-stages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InformaticsMatters%2Fcode-repository-development-stages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InformaticsMatters%2Fcode-repository-development-stages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InformaticsMatters%2Fcode-repository-development-stages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/InformaticsMatters","download_url":"https://codeload.github.com/InformaticsMatters/code-repository-development-stages/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244693846,"owners_count":20494519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-26T02:16:59.783Z","updated_at":"2026-01-04T09:06:21.400Z","avatar_url":"https://github.com/InformaticsMatters.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Code Repository Development Stages\n\nA set of stylistic rules used to classify our software repositories\ninto one of a number of _development stages_. The rules are structured\nto create a number of _numerical stages_ that we consider represent traits of\nsoftware repositories that exhibit a pattern of _increasing 'product quality'_.\n\n**Background**\n\nWe have a lot of software repositories and need to _guide_ each of them so\nthat we converge on a common set of rules that represent best practices\nin software development.\n\nIt is natual, at the start of its life, for code to start as a\n'rough and ready' implementation of a rapidly emerging design or concept.\nDuring this 'pioneering' step initial implementations often avoid\nintroducing too many processes and tools as the trailblazing effort is\nusually hampered and 'bogged-down', with efforts distracted by unnecessary rules.\nIn the early days too many 'quality' rules waste valuable development time\nwhen your code is evolving rapidly where features appear and\ndisappear quickly. At this stage, development practices benefit from\nbeing deliberately relaxed.\n\nAt some stage in the lifetime of the code it becomes _valuable_ and the desire\nto control its behaviour becomes as important (or more important)\nthat enhancing it. It's at this stage, if you've left them out, you might be\nthinking of code formatters, test frameworks, change-log, continuous integration,\nand deployment and delivery options.\n\nRather than switch directly from the prototyping stage to a top-heavy\nprocess that represents the 'ultimate' in assured quality in one step\nthe stages we describe here allow you to adopt the rules you need\nonm a 'sliding scale' to allow gradual migration. And we have a lot of\nrepositories to consider.\n\nThe rules defined here are designed to promote consistency across diverse\nrepositories where developers may use employ different languages and tools.\nThe rules focus on a generic set of processes that should be compatible with\nany software application. The rules help the observer and developer understand\nhow the software is documented, written, tested, built and delivered.\n\n# 2022.1-alpha.1 Rules \n\n**DOCUMENT UNDER REVIEW**\n\nWe have defined policies for four development stages, numbered 0 to 3.\nThe higher the stage number, the more demanding the policy.\n\n_The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,\n“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to\nbe interpreted as described in [RFC 2119]._\n\n## Stage 0\nRepositories at **Stage 0** are the weakest in terms of policies. They\nare repositories that represent new or legacy code that is yet to be promoted\nto a higher stage. \n\nFor agility the policy demands for **Stage 0** are deliberately weak.\n\n1. The repository **SHOULD** have a README file in the root of the repository\n2. The root README format **SHOULD** be one of Markdown (`.md`)\n   or ReStructured Text (`.rst`)\n3. The repository **SHOULD** display our \"Policy Stage 0\" badge in the README\n\n\u003e   **Stage Summary**: In order to understand how to contribute to or use a\n    \"Stage 0\" repository you are likely to need to talk to the author.\n    Process is weak, inconsistent and the build, test and delivery may be unclear\n\nUse the badge in your project's `README.md`:\n```md\n[![Dev Stage: 0](https://img.shields.io/badge/dev%20stage-\u0026#9734;\u0026#9734;\u0026#9734;%20%280%29-000000?labelColor=dc332e)](https://github.com/InformaticsMatters/code-repository-development-stages)\n```\n\nUse the badge in your project's `README.rst`:\n```doctest\n.. image:: https://img.shields.io/badge/dev%20stage-\u0026#9734;\u0026#9734;\u0026#9734;%20%280%29-000000?labelColor=dc332e\n    :target: https://github.com/InformaticsMatters/code-repository-development-stages\n\n```\n\nWhich looks like this:\n![Dev Stage: 0](https://img.shields.io/badge/dev%20stage-\u0026#9734;\u0026#9734;\u0026#9734;%20%280%29-000000?labelColor=dc332e)\n\n\u003e Repositories that have no badge SHOULD be considered \"Stage 0\" repositories.\n\n## Stage 1\n1. The repository **MUST** adopt our [Conventional Commit] message policy\n2. Automated validation of the commit message **MUST** be implemented.\n   This will normally be achieved using git's pre-commit hooks, which can be\n   automatically configured using [pre-commit] and its corresponding\n   `.pre-commit-config.yaml` file\n3. The repository **MUST** have a README file in the root of the repository\n4. The repository **MUST** clearly identify the repository build artefacts,\n   i.e. what gets built (i.e. a container image). Users **MUST** expect\n   to find a **Building** section in the README that contains instructions for\n   building and publishing the artefacts\n5  The repository **MUST** display our \"Policy Stage: 1\" badge in the README\n\n\u003e   **Stage Summary**: Commit messages conform to a standard, are enforced\n    automatically, and it will be clear what the repository's artefacts are\n    and how to build them and find them\n\nUse the badge in your project's `README.md`:\n```md\n[![Dev Stage: 1](https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9734;\u0026#9734;%20%281%29-000000?labelColor=dc332e)](https://github.com/InformaticsMatters/code-repository-development-stages)\n```\n\nUse the badge in your project's `README.rst`:\n```doctest\n.. image:: https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9734;\u0026#9734;%20%281%29-000000?labelColor=dc332e\n    :target: https://github.com/InformaticsMatters/code-repository-development-stages\n\n```\n\nWhich looks like this:\n![Dev Stage: 1](https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9734;\u0026#9734;%20%281%29-000000?labelColor=dc332e)\n\n## Stage 2\n1. The repository **MUST** satisfy all the policies defined in \"Stage 1\"\n2. The repository **MUST** employ CI/CD to build and publish the repo's artefacts\n   For GitHub this will be the use of _Actions_ located in the repository's\n   `.github/workflows` directory. For GitLab this will be the use\n   of a `github-ci.yml` script\n3. The repository **MUST** document a branch policy\n4. Software releases **MUST** be identified using a release (GitHub) or\n   a tag (GitLab or GitHub)\n5. Release numbers **MUST** us semantic versioning, and we typically support\n   3-digit (`1.0.0`) and 2-digit (`2022.1`) styles, including pre-release\n   conventions that introduce suffixes like `-rc.1`\n6. The repository **SHOULD** declare a code style guide\n7. The repository **SHOULD** contain and automatically run [Unit tests]\n\n\u003e   **Stage Summary**: Commit messages conform to a standard, are enforced\n    automatically, repository artefacts are built automatically and\n    development contributions using branches and release mechanisms\n    will be clear\n\nUse the badge in your project's `README.md`:\n```md\n[![Dev Stage: 2](https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9733;\u0026#9734;%20%282%29-000000?labelColor=dc332e)](https://github.com/InformaticsMatters/code-repository-development-stages)\n```\n\nUse the badge in your project's `README.rst`:\n```doctest\n.. image:: https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9733;\u0026#9734;%20%282%29-000000?labelColor=dc332e\n    :target: https://github.com/InformaticsMatters/code-repository-development-stages\n\n```\n\nWhich looks like this:\n![Dev Stage: 2](https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9733;\u0026#9734;%20%282%29-000000?labelColor=dc332e)\n\n## Stage 3\n1. The repository **MUST** satisfy all the policies defined in \"Stage 2\"\n2. The repository **MUST** contain a CHANGELOG that is constructed automatically\n   from the content of commit messages. If you use [Commitizen] as a tool\n   to generate the CHANGELOG our [.cz.yaml] configuration file will be of value -\n   it recognizes the commit message types and structures the CHANGELOG sections\n   accordingly\n3. The CHANGELOG content **MUST** contain details of every commit, regardless of\n   whether the change alters the code's behaviour. For example, documentation\n   and test changes must be present in the CHANGELOG file.\n4. The repository **MUST** declare a code style and the repository **SHOULD**\n   enforce the code style\n5. The repository **MUST** automatically run linting tools that are recognised\n   by the community for the significant languages present in the repository.\n   For example, if a repository contains Java and YAML, the observer can expect \n   to find linters for these language files.\n6. The repository **MUST** contain clear instructions on how to use the artefacts\n   i.e. it must have a guide for deploying and using the artefacts\n7. The repository **SHOULD** publish unit-test coverage statistics\n8. The repository **SHOULD** contain and automatically run [Functional tests]\n\n\u003e   **Summary**: A  strict set of policy rules. Commit messages and code style\n    conform to a standard, and are enforced automatically. Code is built\n    and can be deployed automatically. Users will clearly understand what is built,\n    how it's built, how it's delivered, and what changes have been made\n\nUse the badge in your project's `README.md`:\n```md\n[![Dev Stage: 3](https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9733;\u0026#9733;%20%283%29-000000?labelColor=dc332e)](https://github.com/InformaticsMatters/code-repository-development-stages)\n```\n\nUse the badge in your project's `README.rst`:\n```doctest\n.. image:: https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9733;\u0026#9733;%20%283%29-000000?labelColor=dc332e\n    :target: https://github.com/InformaticsMatters/code-repository-development-stages\n\n```\n\nWhich looks like this:\n![Dev Stage: 3](https://img.shields.io/badge/dev%20stage-\u0026#9733;\u0026#9733;\u0026#9733;%20%283%29-000000?labelColor=dc332e)\n\n## References\n\n- Our [Conventional Commit style guide]\n- Commitizen [.cz.yaml] configuration\n\n## Illustrative repositories\n\n- [data-manager-job-operator]\n\n---\n\n[.cz.yaml]: https://gist.github.com/alanbchristie/19077203307101e9e9d52086488d4921\n[commitizen]: https://pypi.org/project/commitizen\n[conventional commit style guide]: https://discourse.squonk.it/t/conventional-commit-style-guide\n[data-manager-job-operator]: https://github.com/InformaticsMatters/data-manager-job-operator\n[functional tests]: https://en.wikipedia.org/wiki/Functional_testing\n[pre-commit]: https://pre-commit.com\n[rfc 2119]: https://www.ietf.org/rfc/rfc2119.txt\n[unit tests]: https://en.wikipedia.org/wiki/Unit_testing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finformaticsmatters%2Fcode-repository-development-stages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finformaticsmatters%2Fcode-repository-development-stages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finformaticsmatters%2Fcode-repository-development-stages/lists"}