Software Development Guidelines¶
This document describes guidelines for software developers, written for the openEO project. Since the openEO infrastructure will encompasses several programming languages and software environments, this document does not prescribe particular tools or platforms but rather focuses on general principles and methods behind them.
- License: all software developed in the openEO project and published on the openEO GitHub organisation shall be licensed under the Apache 2.0 license. If software repositories deviate from this, or contain code or other artifacts that deviates from this, this shall be described in the
- Location: Official openEO software is developed under the openEO GitHub organisation.
- Proof-of-concept versus sustainable: each repository shall indicate its status: either proof-of-concept, or sustainable. Proof-of-concept code is meant to work but comes without quality assurance. Software repositories with proof-of-concept developments shall clearly say so in the first paragraph of the
- Sustainable code should undergo standard quality checks, and point out its documentation.
- Sustainable code shall undergo code review; no direct commits to master; any commit shall come in the form of a PR, commit after review.
- Sustainable code shall be written in a Test-driven manner, and repositories shall at the top of their
README.mdgive indication of the degree to which code is covered by tests.
- Continuous integration shall be used to indicate code currently passes its test on CI platforms.
- A Code of conduct describes the rules and constraints to developers and contributors.
- Version numbers of sustainable software releases shall follow Semantic Versioning 2.0.0.
Software quality guidelines¶
- software shall be written in such a way that another person can understand its intention
- comment lines shall be used sparsely, but effectively
- reuse of unstable or esoteric libraries shall be avoided
Software documentation guidelines¶
Software documentation shall include: installation instructions usage instructions explain in detail the intention of the software pointers to reference documents explaining overarching concepts
README.md shall point to the documentation.
- sustainable software development shall take place by always having two persons involved in a change to the master branch: individuals push to branches, pull request indicate readiness to be taken up in the master branch, a second developer reviews the pull request before merging it into the master branch.
- software review discussions shall be intelligible for external developers, and serve as implicit documentation of development decisions taken
Software shall be developed in a test-driven fashion, meaning that while the code is written, tests are developed that verify, to a reasonable extent, the correctness of the code. Tools such as codecov.io to automatically indicate the amount of code covered by tests, and code that is not covered by tests shall be used in combination with a continuous integration framework.
Repositories containing running software shall use an appropriate continuous integration platform, such as Travis CI or similar, to show whether the current build passes all checks. This helps understand contributors that the software passes tests on an independent platform, and may give insights in the way the software is compiled, deployed and tested.