Open-Zaak and the Standard for Public Code
Code in the Open
[x] Open Zaak development happens in the open on Github
Requirement | meets | links and notes |
---|---|---|
All source code for any policy and software in use (unless used for fraud detection) MUST be published and publicly accessible. | yes | code, VNG/GEMMA2 policy linked in README |
Contributors MUST NOT upload sensitive information regarding users, their organization or third parties to the repository. | yes | 2020-05-12 review by @EricHerman; ISO 27001 |
Any source code not currently in use (such as new versions, proposals or older versions) SHOULD be published. | yes | releases, docker hub tags |
The source code MAY provide the general public with insight into which source code or policy underpins any specific interaction they have with an organization. |
Bundle policy and source code
[x] Policy bundled, tested, and linked in the documentation, some policy not available in English
Requirement | meets | links and notes |
---|---|---|
A codebase MUST include the policy that the source code is based on. | yes | API specs embeded in the codebase, and linked from documentation |
A codebase MUST include all source code that the policy is based on. | "yes" or "not applicable", do we consider it based on the API? | |
All policy and source code that the codebase is based on MUST be documented, reusable and portable. | yes | code dependencies are OSI |
Policy SHOULD be provided in machine readable and unambiguous formats. | yes | OpenAPI is in machine readable yaml format |
Continuous integration tests SHOULD validate that the source code and the policy are executed coherently. | yes | GitHub workflow, API Test Platform |
Create reusable and portable code
[x] designed to be reusable from the start
Requirement | meets | links and notes |
---|---|---|
The codebase MUST be developed to be reusable in different contexts. | yes | Designed to be so from the start. |
The codebase MUST be independent from any secret, undisclosed, proprietary or non-open licensed code or services for execution and understanding. | yes | installation supports docker, kubernetes, vmware appliances, bare-metal is possible |
The codebase SHOULD be in use by multiple parties. | yes | Deployed in multiple sandbox environments (e.g: Utrecht is testing it, others Den Haag, Delft looking at it.) |
The roadmap SHOULD be influenced by the needs of multiple parties. | yes | Dimpact, market consultation |
Configuration SHOULD be used to make code adapt to context specific needs. | ||
The codebase SHOULD include a machine readable metadata description, for example in a publiccode.yml file. | yes | publiccode.yml |
Code and its documentation SHOULD NOT contain situation-specific information. | yes | Some GCloud examples but nothing required; no credentials and documentation suggests using secret generators |
Welcome contributors
[ ] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
The codebase MUST allow anyone to submit suggestions for changes to the codebase. | yes | requests |
The codebase MUST include contribution guidelines explaining what kinds of contributions are welcome and how contributors can get involved, for example in a CONTRIBUTING file. | yes | CONTRIBUTING, Documentation |
The codebase SHOULD advertise the committed engagement of involved organizations in the development and maintenance. | yes | Readme |
The codebase SHOULD document the governance of the codebase, contributions and its community, for example in a GOVERNANCE file. | no | draft GOVERNANCE file |
The codebase SHOULD have a publicly available roadmap. | no | Issues are not yet collected into a roadmap view; tech-debt and tech-wishlist not yet collected into a technical roadmap |
The codebase MAY include a code of conduct for contributors. | no | no email address in the Code of conduct to report incidents |
Make contributing easy
[x] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
The codebase MUST have a public issue tracker that accepts suggestions from anyone. | yes | issues |
The codebase MUST include instructions for how to privately report security issues for responsible disclosure. | yes | Reporting security issues |
The documentation MUST link to both the public issue tracker and submitted codebase changes, for example in a README file. | yes | Documentation, CONTRIBUTING.md |
The codebase MUST have communication channels for users and developers, for example email lists. | yes | Mailing list, github issues, VNG slack channel (requires an invite) |
The documentation SHOULD include instructions for how to report potentially security sensitive issues on a closed channel. | yes | SECURITY.rst |
Maintain version control
[x] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
The community MUST have a way to maintain version control for the code. | yes | GitHub |
All files in a codebase MUST be version controlled. | yes | git |
All decisions MUST be documented in commit messages. | yes | Commit messages are sufficiently detailed or contain links to detail; the repo has a policy and a pull_request_template.md which encourages referencing an issue and describing the changes @ericherman 2022-0321 |
Every commit message MUST link to discussions and issues wherever possible. | yes | for non-trivial commits |
The codebase SHOULD be maintained in a distributed version control system. | yes | git |
Contributors SHOULD group relevant changes in commits. | yes | PRs |
Maintainers SHOULD mark released versions of the codebase, for example using revision tags or textual labels. | yes | releases |
Contributors SHOULD prefer file formats where the changes within the files can be easily viewed and understood in the version control system. | yes | mostly code and Restructured Text or Markdown |
Contributors MAY sign their commits and provide an email address, so that future contributors are able to contact past contributors with questions about their work. | yes | Commits have email addresses, release tags GPG signed |
Require review of contributions
[x] Practices are good, would like to see explicit docs
Requirement | meets | links and notes |
---|---|---|
All contributions that are accepted or committed to release versions of the codebase MUST be reviewed by another contributor. | yes | PRs |
Reviews MUST include source, policy, tests and documentation. | yes | repo is configured, tests span, practices right, yet documentation could be more explicit on this point |
Reviewers MUST provide feedback on all decisions to not accept a contribution. | yes | documentations/contrib guidelines could copy-paste from the employement handbook, PRs |
Contributions SHOULD conform to the standards, architecture and decisions set out in the codebase in order to pass review. | yes | PRs, django best practices |
Reviews SHOULD include running both the code and the tests of the codebase. | yes | CI and manual validation required, not clearly documented yet (in handbook) |
Contributions SHOULD be reviewed by someone in a different context than the contributor. | (some) not applicable yet | |
Version control systems SHOULD NOT accept non-reviewed contributions in release versions. | yes | master branch protected, release process |
Reviews SHOULD happen within two business days. | yes | no official policy, is the practice |
Reviews MAY be performed by multiple reviewers. | mostly |
Document codebase objectives
[x] Objectives are clear in the introduction documenation
Requirement | meets | links and notes |
---|---|---|
The codebase MUST contain documentation of its objectives – like a mission and goal statement – that is understandable by developers and designers so that they can use or contribute to the codebase. | yes | "Open Zaak is based on the API reference implementations by VNG Realisatie to create a production-grade product that can be used by municipalities." introduction |
Codebase documentation SHOULD clearly describe the connections between policy objectives and codebase objectives. | yes | |
The codebase MAY contain documentation of its objectives for the general public. | could elaborate for general public: Common Ground, data security, GDPR requests and such |
Document the code
[x] documentation is good across the board, “recipies” would be nice
Requirement | meets | links and notes |
---|---|---|
All of the functionality of the codebase – policy as well as source – MUST be described in language clearly understandable for those that understand the purpose of the code. | yes | additional docs are generated from code comments |
The documentation of the codebase MUST contain: a description of how to install and run the source code, examples demonstrating the key functionality. | yes | getting started, post-install checklist, improvement: add demo fixtures/instructions |
The documentation of the codebase SHOULD contain: a high level description that is clearly understandable for a wide audience of stakeholders, like the general public and journalists, a section describing how to install and run a standalone version of the source code, including, if necessary, a test dataset, examples for all functionality. | documentation, would like to see standard recipies and examples of more fuctionality | |
There SHOULD be continuous integration tests for the quality of the documentation. | yes | link checks, build checks, Travis config |
The documentation of the codebase MAY contain examples that make users want to immediately start using the codebase. | ||
The code MAY be tested by using examples in the documentation. |
Use plain English
[ ] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
All codebase documentation MUST be in English. | manual in Dutch | |
All code MUST be in English, except where policy is machine interpreted as code. | ||
All bundled policy not available in English MUST have an accompanying summary in English. | ||
Any translation MUST be up to date with the English version and vice versa. | TODO: add translations of user-facing texts (NL -> EN) (makemessages) | |
There SHOULD be no acronyms, abbreviations, puns or legal/non-English/domain specific terms in the codebase without an explanation preceding it or a link to an explanation. | Domain specific Dutch terms could be in a glossary which is also translated in English. | |
The name of the codebase SHOULD be descriptive and free from acronyms, abbreviations, puns or organizational branding. | yes | |
Documentation SHOULD aim for a lower secondary education reading level, as recommended by the Web Content Accessibility Guidelines 2. | Would be good to get an evaluation of this prior to investing in translation. | |
Any code, documentation or tests MAY have a translation. |
Use open standards
[x] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
For features of a codebase that facilitate the exchange of data the codebase MUST use an open standard that meets the Open Source Initiative Open Standard Requirements. | yes | The Zaakgericht Werken in het Gemeentelijk Gegevenslandschap meets the 5 criteria of the Open Standards Requirement for Software |
If no existing open standard is available, effort SHOULD be put into developing one. | n/a | |
Standards that are machine testable SHOULD be preferred over those that are not. | yes | see test suite |
Functionality using features from a non-open standard (one that doesn’t meet the Open Source Initiative Open Standard Requirements) MAY be provided if necessary, but only in addition to compliant features. | ||
All non-compliant standards used MUST be recorded clearly in the documentation. | n/a | |
The codebase SHOULD contain a list of all the standards used with links to where they are available. | yes |
Use continuous integration
[ ] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
All functionality in the source code MUST have automated tests. | 96% codecoverage, small amount of admin UI code not tested | |
Contributions MUST pass all automated tests before they are admitted into the codebase. | yes | github checks |
Contributions MUST be small. | refer to contributing guidelines (single issue, single PR solves single issue) | |
The codebase MUST have active contributors. | yes | pulse |
Source code test and documentation coverage SHOULD be monitored. | yes | |
Policy and documentation MAY have testing for consistency with the source and vice versa. | yes | |
Policy and documentation MAY have testing for style and broken links. | yes | docs tests, flake8/isort/black |
Publish with an open license
[x] Remove confusion in the documentation footer
Requirement | meets | links and notes |
---|---|---|
All code and documentation MUST be licensed such that it may be freely reusable, changeable and redistributable. | yes | copyright marks in the footer? -> check if we can add license to footer (sphinx conf), but explicit open license |
Software source code MUST be licensed under an OSI-approved open source license. | yes | LICENSE |
All code MUST be published with a license file. | yes | LICENSE |
Contributors MUST NOT be required to transfer copyright of their contributions to the codebase. | yes | |
All source code files in the codebase SHOULD include a copyright notice and a license header that are machine readable. | yes | 2020-08-03 review by @ericherman |
Codebases MAY have multiple licenses for different types of code and documentation. | N/A |
Use a coherent style
[x] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
Contributions MUST adhere to either a coding or writing style guide, either the codebase community’s own or an existing one that is advertised in or part of the codebase. | yes | Style guides |
Contributions SHOULD pass automated tests on style. | yes | |
The codebase SHOULD include inline comments and documentation for non-trivial sections. | yes | add to contributing guidelines |
The style guide MAY include sections on understandable English. |
Document codebase maturity
[x] compliant with this criterion.
Requirement | meets | links and notes |
---|---|---|
A codebase MUST be versioned. | yes | version list |
A codebase that is ready to use MUST only depend on other codebases that are also ready to use. | yes | Open source dependencies |
A codebase that is not yet ready to use MUST have one of these labels: prototype - to test the look and feel, and to internally prove the concept of the technical possibilities, alpha - to do guided tests with a limited set of users, beta - to open up testing to a larger section of the general public, for example to test if the codebase works at scale, pre-release version - code that is ready to be released but hasn’t received formal approval yet. | N/A | Is ready |
A codebase SHOULD contain a log of changes from version to version, for example in the CHANGELOG. | yes | changelog |