Public code

Open-Zaak and the Standard for Public Code

Open-Zaak and the Standard for Public Code version 0.7.1

Link to commitment to meet the Standard for Public Code: CONTRIBUTING

Code in the open

criterion met.
MeetsRequirementNotes and links
yes All source code for any policy in use (unless used for fraud detection) MUST be published and publicly accessible. code, VNG/GEMMA2 policy linked in README
yes All source code for any software in use (unless used for fraud detection) MUST be published and publicly accessible. code
yes The codebase MUST NOT contain sensitive information regarding users, their organization or third parties. 2020-05-12 review by @EricHerman; ISO 27001
yes Any source code not currently in use (such as new versions, proposals or older versions) SHOULD be published. releases , docker hub tags
Documenting which source code or policy underpins any specific interaction the general public may have with an organization is OPTIONAL.

Bundle policy and source code

criterion met.
MeetsRequirementNotes and links
yes The codebase MUST include the policy that the source code is based on. API specs embeded in the codebase, and linked from documentation
If a policy is based on source code, that source code MUST be included in the codebase, unless used for fraud detection. "yes" or "not applicable", do we consider it based on the API?
yes Policy SHOULD be provided in machine readable and unambiguous formats. OpenAPI is in machine readable yaml format
yes Continuous integration tests SHOULD validate that the source code and the policy are executed coherently. GitHub workflow, API Test Platform

Make the codebase reusable and portable

criterion met.
MeetsRequirementNotes and links
yes The codebase MUST be developed to be reusable in different contexts. Designed to be so from the start.
yes The codebase MUST be independent from any secret, undisclosed, proprietary or non-open licensed software or services for execution and understanding. installation supports docker, kubernetes, vmware appliances, bare-metal is possible
yes The codebase SHOULD be in use by multiple parties.
yes The roadmap SHOULD be influenced by the needs of multiple parties. Dimpact, market consultation
The development of the codebase SHOULD be a collaboration between multiple parties. The technical steering has multiple parties, but the development is centered on a single vendor.
Configuration SHOULD be used to make source code adapt to context specific needs.
The codebase SHOULD be localizable. translations provided for catalogs but not yet complete
yes Source code and its documentation SHOULD NOT contain situation-specific information. Some GCloud examples but nothing required; no credentials and documentation suggests using secret generators
Codebase modules SHOULD be documented in such a way as to enable reuse in codebases in other contexts.
yes The software SHOULD NOT require services or platforms available from only a single vendor.

Welcome contributors

criterion met.
MeetsRequirementNotes and links
yes The codebase MUST allow anyone to submit suggestions for changes to the codebase. requests
yes 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. CONTRIBUTING, Documentation
no The codebase MUST document the governance of the codebase, contributions and its community, for example in a `GOVERNANCE` file. draft GOVERNANCE file
The contribution guidelines SHOULD document who is expected to cover the costs of reviewing contributions.
yes The codebase SHOULD advertise the committed engagement of involved organizations in the development and maintenance. Readme
no The codebase SHOULD have a publicly available roadmap. Issues are not yet collected into a roadmap view; tech-debt and tech-wishlist not yet collected into a technical roadmap
yes The codebase SHOULD publish codebase activity statistics. GitHub pulse
yes Including a code of conduct for contributors in the codebase is OPTIONAL. no email address in the Code of conduct to report incidents

Make contributing easy

criterion met.
MeetsRequirementNotes and links
yes The codebase MUST have a public issue tracker that accepts suggestions from anyone. issues
yes The documentation MUST link to both the public issue tracker and submitted codebase changes, for example in a `README` file. Documentation, CONTRIBUTING
yes The codebase MUST have communication channels for users and developers, for example email lists. Mailing list, issues, VNG slack channel (requires an invite)
yes There MUST be a way to report security issues for responsible disclosure over a closed channel. Reporting security issues
yes The documentation MUST include instructions for how to report potentially security sensitive issues. SECURITY.rst

Maintain version control

criterion met.
MeetsRequirementNotes and links
yes All files in the codebase MUST be version controlled. git
yes All decisions MUST be documented in commit messages. 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-03-21
yes Every commit message MUST link to discussions and issues wherever possible. for non-trivial commits
yes The codebase SHOULD be maintained in a distributed version control system. git
yes Contribution guidelines SHOULD require contributors to group relevant changes in commits. Implied in CONTRIBUTING but could be more explicit
yes Maintainers SHOULD mark released versions of the codebase, for example using revision tags or textual labels. releases
Contribution guidelines SHOULD encourage file formats where the changes within the files can be easily viewed and understood in the version control system. While most files are code, Restructured Text or Markdown, nothing in the guidelines
yes It is OPTIONAL for contributors to sign their commits and provide an email address, so that future contributors are able to contact past contributors with questions about their work. Commits have email addresses, release tags GPG signed

Require review of contributions

criterion met.
MeetsRequirementNotes and links
yes All contributions that are accepted or committed to release versions of the codebase MUST be reviewed by another contributor. PRs
yes Reviews MUST include source, policy, tests and documentation. repo is configured, tests span, practices right, yet documentation could be more explicit on this point
yes Reviewers MUST provide feedback on all decisions to not accept a contribution. documentations/contrib guidelines could copy-paste from the employement handbook, PRs
yes The review process SHOULD confirm that a contribution conforms to the standards, architecture and decisions set out in the codebase in order to pass review. PRs, django best practices, process could be more explicitly documented
yes Reviews SHOULD include running both the software and the tests of the codebase. 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
yes Version control systems SHOULD NOT accept non-reviewed contributions in release versions. main branch protected, release process
yes Reviews SHOULD happen within two business days. no official policy, is the practice
Performing reviews by multiple reviewers is OPTIONAL. mostly

Document codebase objectives

criterion met.
MeetsRequirementNotes and links
yes 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. "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
yes Codebase documentation SHOULD clearly describe the connections between policy objectives and codebase objectives.
Documenting the objectives of the codebase for the general public is OPTIONAL. could elaborate for general public: Common Ground, data security, GDPR requests and such

Document the code

criterion met.
MeetsRequirementNotes and links
yes All of the functionality of the codebase, policy as well as source code, MUST be described in language clearly understandable for those that understand the purpose of the codebase. additional docs are generated from code comments
yes The documentation of the codebase MUST contain a description of how to install and run the software. getting started, post-install checklist
yes The documentation of the codebase MUST contain examples demonstrating the key functionality. Recipes 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. documentation, would like to see standard recipies and examples of more functionality
yes The documentation of the codebase SHOULD contain a section describing how to install and run a standalone version of the source code, including, if necessary, a test dataset. installation
yes The documentation of the codebase SHOULD contain examples for all functionality. manual
The documentation SHOULD describe the key components or modules of the codebase and their relationships, for example as a high level architectural diagram. basics about the Frontend and Backend described in principles
yes There SHOULD be continuous integration tests for the quality of the documentation. link checks, build checks, GitHub Actions
Including examples that make users want to immediately start using the codebase in the documentation of the codebase is OPTIONAL.

Use plain English

criterion met.
MeetsRequirementNotes and links
All codebase documentation MUST be in English. manual in Dutch
All source 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.
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.
Providing a translation of any code, documentation or tests is OPTIONAL.

Use open standards

criterion met.
MeetsRequirementNotes and links
yes For features of the codebase that facilitate the exchange of data the codebase MUST use an open standard that meets the Open Source Initiative Open Standard Requirements. The Zaakgericht Werken in het Gemeentelijk Gegevenslandschap meets the 5 criteria of the Open Standards Requirement for Software
n/a Any non-open standards used MUST be recorded clearly as such in the documentation.
yes Any standard chosen for use within the codebase MUST be listed in the documentation with a link to where it is available. API-specifications
n/a Any non-open standards chosen for use within the codebase MUST NOT hinder collaboration and reuse.
n/a If no existing open standard is available, effort SHOULD be put into developing one.
yes Open standards that are machine testable SHOULD be preferred over open standards that are not. e.g.: Zaken API
N/A Non-open standards that are machine testable SHOULD be preferred over non-open standards that are not.

Use continuous integration

criterion met.
MeetsRequirementNotes and links
All functionality in the source code MUST have automated tests. 96% code coverage, small amount of admin UI code not tested
yes Contributions MUST pass all automated tests before they are admitted into the codebase. github checks
yes The codebase MUST have guidelines explaining how to structure contributions. CONTRIBUTING
yes The codebase MUST have active contributors who can review contributions. pulse
yes Automated test results for contributions SHOULD be public.
The codebase guidelines SHOULD state that each contribution should focus on a single issue. single PR to solve a single issue could be clearer in guidelines
yes Source code test and documentation coverage SHOULD be monitored.
yes Testing policy and documentation for consistency with the source and vice versa is OPTIONAL.
yes Testing policy and documentation for style and broken links is OPTIONAL. docs tests, flake8/isort/black
Testing the software by using examples in the documentation is OPTIONAL.

Publish with an open license

criterion met.
MeetsRequirementNotes and links
yes All source code and documentation MUST be licensed such that it may be freely reusable, changeable and redistributable. copyright marks in the footer? -> check if we can add license to footer (sphinx conf), but explicit open license
yes Software source code MUST be licensed under an OSI-approved or FSF Free/Libre license. EUPL 1.2 LICENSE
yes All source code MUST be published with a license file. LICENSE
yes 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. 2020-08-03 review by @ericherman
Having multiple licenses for different types of source code and documentation is OPTIONAL.

Make the codebase findable

criterion met.
MeetsRequirementNotes and links
yes The name of the codebase SHOULD be descriptive and free from acronyms, abbreviations, puns or organizational branding.
yes The codebase SHOULD have a short description that helps someone understand what the codebase is for or what it does. There are short discriptions on openzaak.org and on GitHub, but not consistent.
Maintainers SHOULD submit the codebase to relevant software catalogs.
yes The codebase SHOULD have a website which describes the problem the codebase solves using the preferred jargon of different potential users of the codebase (including technologists, policy experts and managers). openzaak.org
yes The codebase SHOULD be findable using a search engine by codebase name.
The codebase SHOULD be findable using a search engine by describing the problem it solves in natural language.
The codebase SHOULD have a unique and persistent identifier where the entry mentions the major contributors, repository location and website.
yes The codebase SHOULD include a machine-readable metadata description, for example in a publiccode.yml file. publiccode.yaml
yes A dedicated domain name for the codebase is OPTIONAL.
Regular presentations at conferences by the community are OPTIONAL.

Use a coherent style

criterion met.
MeetsRequirementNotes and links
yes The codebase MUST use a coding or writing style guide, either the codebase community's own or an existing one referred to in the codebase. Style guides
yes Contributions SHOULD pass automated tests on style.
yes The style guide SHOULD include expectations for inline comments and documentation for non-trivial sections. add to contributing guidelines
Including expectations for understandable English in the style guide is OPTIONAL.

Document codebase maturity

criterion met.
MeetsRequirementNotes and links
yes The codebase MUST be versioned. version list
yes The codebase MUST prominently document whether or not there are versions of the codebase that are ready to use.
yes Codebase versions that are ready to use MUST only depend on versions of other codebases that are also ready to use. Open source dependencies
yes The codebase SHOULD contain a log of changes from version to version, for example in the `CHANGELOG`. changelog
The method for assigning version identifiers SHOULD be documented. Not explicitly documented as following semantic versioning
yes It is OPTIONAL to use semantic versioning. Not explicitly documented as following semantic versioning