Full assessment of maintenance hygiene of all repositories

[nickevansuk]

For current repos:

• Purpose should be clearly stated, and now it fits into the rest of the infrastructure
• What design decisions need to be documented?
• Installation instructions clear (and in a consistent place across all repos - e.g. the second heading?)
• What manual maintenance needs to documented (if not already automated)?
• If someone was to start work on this repo, would they have everything they need to tackle the issues in there?
• Are all issues and PRs clear?
• Do issue and PR templates exist?
• Is CONTRIBUTOR.MD sufficient
• Correct licenses applied (and confirmed via script, see also this issue)
• Does it have unit tests?
• Is the README.md clear? Is it clear where this repo fits in amongst the other repositories?
• Are dependencies clear (perhaps there should be a little mermaid diagram)
• Are dependency updates automated (e.g. here)?
• Are downstream dependency PRs automated (e.g. here)?
• Test coverage?
• Is it still required? Can it be archived?
• Status of the repo (e.g. experimental, production, archive)
• Is this classified as supporting a "critical centrally hosted service" (e.g. activity-list, ns, ns-beta, etc.) (notes below for ease, however should probably be split out into a separate issue)
  • Tooling such as the validator and libraries such as models-php are not critical centrally hosted services as they will not break live OA implementations if they were to go offline.
  • N.B OpenActive's infrastructure always aims to absolutely minimise centrally maintained and centrally hosted critical production services. Services should only be centrally maintained or hosted if there is absolutely no other way of achieving the objective.
  • This is all about avoiding a situation where one OA maintainer with a single erroneous commit or a Heroku dyno bouncing can accidentally take down the whole OA ecosystem
  • As an aside - we should keep a specific registry of these, and ensure there's a process where maintainers/contributors add new services to this registry, to ensure they are fully aware of the implications of this.
  • A great example of what we're trying to prevent is https://github.com/openactive/dataset-directory (which could easily become a defacto "critical centrally hosted service", just because it is being provided with a live endpoint in an official repo). We should instead prefer https://github.com/openactive/dataset-utils.
• Maintainers assigned using https://github.com/orgs/openactive/teams
• Tech debt RAG status
• Language

For archived repos:

• Explanation of function
• Reason for archiving
• Disclaimer present? ("this is no longer maintained, use at your own risk")

---

Suggestion of approach: start with a spreadsheet, perhaps once spreadsheet is finalised the assessment data is either part of the README of each repo, or we use custom properties

Also check if there's any prior art we can use here, e.g.:

• https://sarahthiery.medium.com/a-beginners-guide-to-github-repo-hygiene-3a7a872ab898
• https://dev.to/pwd9000/github-repository-best-practices-23ck
• https://joost.blog/healthy-github-repository/

---

Other notes:

New Tiny Issue: https://github.com/openactive/public-chat/blob/master/code-of-conduct/index.md should be moved to be the default code of conduct for the whole org

Test suite tests reference implementation, and visa versa. Arrows represent this.

Separate status page and visualiser

Add categories:

• Specifications
• Production Infrastructure (including namespace, data catalogues, activity list, etc)
• Ontology Management (activity list editor, other editors)
  • huge tech debt here, as editors are duplicated
• Tooling (validator, status page, etc)