diff --git a/_sidebar.md b/_sidebar.md index b3e11f5e..428a3217 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -1,7 +1,6 @@ * [Introduction](/README.md) * [Best practices](/best_practices/overview.md) - * [Checklist](/best_practices/checklist.md) * [Version Control](/best_practices/version_control.md) * [Code Quality](/best_practices/code_quality.md) * [Code Review](/best_practices/code_review.md) @@ -42,8 +41,3 @@ * [Project Reviews](/nlesc_specific/projects/project_reviews.md) * [Communication](/nlesc_specific/projects/communication.md) * [End of a Project](/nlesc_specific/projects/end_of_a_project.md) - * [Checklist](/nlesc_specific/checklist.md) - * [Development stages matrix](/nlesc_specific/checklist_matrix.md) - * [Prototype phase](/nlesc_specific/checklist/checklist_prototype.md) - * [Prerelease phase](/nlesc_specific/checklist/checklist_prerelease.md) - * [Mature phase](/nlesc_specific/checklist/checklist_mature.md) diff --git a/best_practices/checklist.md b/best_practices/checklist.md deleted file mode 100644 index acaf9cc2..00000000 --- a/best_practices/checklist.md +++ /dev/null @@ -1,45 +0,0 @@ -# Software checklist - -Here we provide a short checklist for software projects, the rest of this chapter elaborates on the various point in this list. - -The __bare minimum__ that every software project should do, from the start, is: - -* Pick & include an [open source license](licensing.md) -* Use [version control](version_control.md) -* Use a [publicly accessible](version_control.md#repositories-should-be-public) - version controlled repository -* Add a [readme describing the project](documentation.md#readme) - -We recommend that you also do the following (from the start of the project): - -* Use [code quality tools](code_quality.md) -* [Testing](testing.md) -* Use [standards](standards.md) - -Additional steps depend on the goal of the software (zero or more can apply): - -* [I'm publishing a paper](#im-publishing-a-paper) -* [I'm expecting users](#im-expecting-users) -* [I'm expecting contributors](#im-expecting-contributors) - -A more thorough checklist is the [Core Infrastructures Initiative Badge Best Practices Badge Program](https://bestpractices.coreinfrastructure.org/en/criteria/0). This list is not aimed at research software, and the criteria (for example those focused on security) might go beyond what is necessary. However the aim is **not** to show perfect compliance, but rather to be transparent about the state of the code while providing the necessary guidance on which aspects could be improved. - -## I'm publishing a paper - -* Add a [CITATION.cff file](documentation.md#software-citation) -* [Make your software citable](https://the-turing-way.netlify.app/communication/citable/citable-cite#citing-software) -* Cite DOI in paper - -## I'm expecting users - -* [Release](releases.md) your software -* Provide [user documentation](documentation.md) -* [Easy installation](releases.md#one-command-install) -* Provide issue tracker - -## I'm expecting contributors - -* Provide [development documentation](documentation.md#source-code-documentation) -* Provide a [means of communication](communication.md#discussion-list) -* Implement and add a [code of conduct](documentation.md#code-of-conduct) -* [Contribution guideline](documentation.md#contribution-guidelines) diff --git a/nlesc_specific/checklist.md b/nlesc_specific/checklist.md deleted file mode 100644 index 680516aa..00000000 --- a/nlesc_specific/checklist.md +++ /dev/null @@ -1,72 +0,0 @@ -# Software checklist - -This section contains a list of items which are required to help software reach a sufficient quality standard. The following list of items links to explanation in other sections of this chapter. - -The [checklist matrix](./checklist_matrix.md) provides an indication of which items are important at different development stages. - -## [Version control](../best_practices/version_control.md) - -- [version control from the beginning of the project](../best_practices/version_control.md#version-control-from-the-beginning-of-the-project) -- [use git as version control system (vcs)](../best_practices/version_control.md#use-git-as-version-control-system-vcs) -- [choose one branching model](../best_practices/version_control.md#choose-one-branching-model) -- [public vcs repository](../best_practices/version_control.md#public-vcs-repository) -- [meaningful commit messages](../best_practices/version_control.md#meaningful-commit-messages) - -## [Releases](../best_practices/releases.md) - -- [semantic versioning](../best_practices/releases.md#semantic-versioning) -- [tagged releases](../best_practices/releases.md#tagged-releases) -- [CHANGELOG.md](../best_practices/releases.md#changelogmd) -- [one command install](../best_practices/releases.md#one-command-install) -- [package in package manager](../best_practices/releases.md#package-in-package-manager) -- [discuss release cycle with coordinator](../best_practices/releases.md#discuss-release-cycle-with-coordinator) -- [release quick-scan by other engineer](../best_practices/releases.md#release-quick-scan-by-other-engineer) -- [Dissemination](../best_practices/releases.md#dissemination) - -## [Licensing](../best_practices/licensing.md) - -- [Apache 2 license](../best_practices/licensing.md#apache-2-license) -- [compatible license of all libraries](../best_practices/licensing.md#compatible-licenses-of-all-libraries) -- [NOTICE(.txt|.md)](../best_practices/licensing.md#notice) - -## [Communication](../best_practices/communication.md) - -- [home page](../best_practices/communication.md#home-page) -- [discussion list](../best_practices/communication.md#discussion-list) -- [demo docker image in dockerhub (with Dockerfile)](../best_practices/communication.md#demo-docker-image-in-dockerhub-with-dockerfile) -- [an online demo](../best_practices/communication.md#an-online-demo) -- [screencast](../best_practices/communication.md#screencast) - -## [Code Quality](../best_practices/code_quality.md) - -- [use editorconfig](../best_practices/code_quality.md#use-editorconfig) -- [code style applied in automated way](https://the-turing-way.netlify.app/reproducible-research/code-quality/code-quality-style.html#automatic-formatting) - -## [Testing](../best_practices/testing.md) - -- [unit tests](../best_practices/testing.md#unit-tests) -- [continuous integration](../best_practices/testing.md#continuous-integration) -- [continuous code coverage](../best_practices/testing.md#continuous-code-coverage) -- [end2end test](../best_practices/testing.md#end2end-tests) -- [dependencies tracking](../best_practices/testing.md#dependencies-tracking) - -## [Documentation](../best_practices/documentation.md) - -- [README.md](../best_practices/documentation.md#readmemd) -- [well defined functionality](../best_practices/documentation.md#well-defined-functionality) -- [source code documentation](../best_practices/documentation.md#source-code-documentation) -- [usage documentation](../best_practices/documentation.md#usage-documentation) -- [documented development setup](../best_practices/documentation.md#documented-development-setup) -- [contribution guidelines](../best_practices/documentation.md#contribution-guidelines) -- [code of conduct](../best_practices/documentation.md#code-of-conduct) -- [documented code style](../best_practices/documentation.md#documented-code-style) -- [how to file a bug report](../best_practices/documentation.md#howto-bug-report) -- [explained meaning of issue labels](../best_practices/documentation.md#explained-meaning-of-issue-labels) -- [DOI or PID](../best_practices/documentation.md#doi-or-pid) -- [CITATION.cff file](../best_practices/documentation.md#software-citation) -- [print software version](../best_practices/documentation.md#print-software-version) - -## [Standards](../best_practices/standards.md) - -- [Exchange formats](../best_practices/standards.md#exchange-formats) -- [Protocols](../best_practices/standards.md#protocols) diff --git a/nlesc_specific/checklist/checklist_mature.md b/nlesc_specific/checklist/checklist_mature.md deleted file mode 100644 index b4c222ba..00000000 --- a/nlesc_specific/checklist/checklist_mature.md +++ /dev/null @@ -1,88 +0,0 @@ -# Checkmatrix for software projects. - -Printable check-list -- complete this checklist to ensure your project is in good shape. - - -## Version Control - -Item / Phase | Done | -:------------|:---------:| -use git as version control system (vcs)| -use [GitHub flow branching model](https://guides.github.com/introduction/flow/) (use feature branches and pull requests)| -public vcs repository ([github](https://github.com/))| -meaningful commit messages| - - -## Releases - -Item / Phase | Done | -:------------|:---------:| -[semantic versioning](http://semver.org/)| -tagged releases ([github releases](https://help.github.com/categories/releases/))| -CHANGELOG.md ([Keep a CHANGELOG](http://keepachangelog.com/))| -one command install ([pip](https://pypi.python.org/pypi/pip), [npm](https://www.npmjs.com/package/npm) etc)| -package in package manager ([pypi](https://pypi.python.org/), [npm](https://www.npmjs.com/) etc)| -discuss release cycle with coordinator| -release quick-scan by other engineer (is documentation understandable, can it be installed, etc)| -notify our Communications Advisor for dissemination (news item on site / annual report, etc)| - -## Licensing - -Item / Phase | Done | -:------------|:---------:| -[Apache 2 license](http://www.apache.org/licenses/LICENSE-2.0)| -compatible license of all libraries| -`NOTICE(.txt or .md)` listing licenses, request citation of paper if applicable| - -## Communication - -Item / Phase | Done | -:------------|:---------:| -home page with all the necessary introduction information, links to documenation, source code (github) and latest release download (eg. [github.io pages](https://pages.github.com/))| -project discussion list (github issues, mailing list, not private email) for all project related discussions from the beginning of the project| -for services: a demo docker image in dockerhub (with Dockerfile)| -for websites: an online demo| -Pitch presentation (1 to 3 slides)| - -## Testing - -Item / Phase | Done | -:------------|:---------:| -[unit tests](https://en.wikipedia.org/wiki/Unit_testing)| -build tests| -[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration), using a [publicly available service](../../best_practices/testing.md#Online-services-for-continuous-integration) -continuous code coverage and code quality metrics public, minimum 70% coverage required| -end2end test for (web) user interfaces| -track dependencies (with [Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates) or other service depending on codebase language)| - -## Documentation - -Item / Phase | Done | -:------------|:---------:| -`README.md` - clear explanation of the goal of the project with pointers to other documentation resources. Use [GitHub flavored markdown](https://help.github.com/categories/writing-on-github) for, e.g., [syntax highlighting](https://help.github.com/articles/creating-and-highlighting-code-blocks).| -well defined functionality| -source code documentation| -usage documentation| -documented development setup (good example is [Getting started with khmer development](http://khmer.readthedocs.org/en/latest/dev/getting-started.html))| -contribution guidelines [example](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)| -code of conduct ([contributor covenant](http://contributor-covenant.org/))| -documented code style| -meaning of issue labels used| -DOI or PID ([making your code citable](https://guides.github.com/activities/citable-code/))| - - -## Development setup - -Item / Phase | Done | -:------------|:---------:| -using the eScienc Center coding style is required| -[editorconfig](http://editorconfig.org/)| -applied code style in automated way if possible (i.e using linters and code formaters)| -dev environment docker images in Dockerhub (with Dockerfile)| - -## Use standards - -Item / Phase | Done | -:------------|:---------:| -exchange format (Unicode, W3C, OGN, NetCDF, etc)| -protocols (HTTP, TCP, TLS, etc)| diff --git a/nlesc_specific/checklist/checklist_prerelease.md b/nlesc_specific/checklist/checklist_prerelease.md deleted file mode 100644 index 9a6a58b1..00000000 --- a/nlesc_specific/checklist/checklist_prerelease.md +++ /dev/null @@ -1,73 +0,0 @@ -# Checkmatrix for software projects. - -Printable check-list -- complete this checklist to ensure your project is in good shape. - - -##Version Control - -Item / Phase | Done | -:------------|:---------:| -use git as version control system (vcs)| -use [GitHub flow branching model](https://guides.github.com/introduction/flow/) (use feature branches and pull requests)| -public vcs repository ([github](https://github.com/))| -meaningful commit messages| - - -##Releases - -Item / Phase | Done | -:------------|:---------:| -discuss release cycle with coordinator| - -##Licensing - -Item / Phase | Done | -:------------|:---------:| -[Apache 2 license](http://www.apache.org/licenses/LICENSE-2.0)| -compatible license of all libraries| -`NOTICE(.txt or .md)` listing licenses, request citation of paper if applicable| - -##Communication - -Item / Phase | Done | -:------------|:---------:| -project discussion list (github issues, mailing list, not private email) for all project related discussions from the beginning of the project| -Pitch presentation (1 to 3 slides)| - -##Testing - -Item / Phase | Done | -:------------|:---------:| -[unit tests](https://en.wikipedia.org/wiki/Unit_testing)| -build tests| -[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration), using a [publicly available service](../../best_practices/testing.md#Online-services-for-continuous-integration)| - -##Documentation - -Item / Phase | Done | -:------------|:---------:| -`README.md` - clear explanation of the goal of the project with pointers to other documentation resources. Use [GitHub flavored markdown](https://help.github.com/categories/writing-on-github) for, e.g., [syntax highlighting](https://help.github.com/articles/creating-and-highlighting-code-blocks).| -well defined functionality| -source code documentation| -usage documentation| -documented development setup (good example is [Getting started with khmer development](http://khmer.readthedocs.org/en/latest/dev/getting-started.html))| -contribution guidelines [example](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)| -code of conduct ([contributor covenant](http://contributor-covenant.org/))| -documented code style| -meaning of issue labels used| - -## Development setup - -Item / Phase | Done | -:------------|:---------:| -using the eScience Center coding style is required| -[editorconfig](http://editorconfig.org/)| -applied code style in automated way if possible (i.e using linters and code formaters)| -dev environment docker images in Dockerhub (with Dockerfile)| - -## Use standards - -Item / Phase | Done | -:------------|:---------:| -exchange format (Unicode, W3C, OGN, NetCDF, etc)| -protocols (HTTP, TCP, TLS, etc)| diff --git a/nlesc_specific/checklist/checklist_prototype.md b/nlesc_specific/checklist/checklist_prototype.md deleted file mode 100644 index 85192245..00000000 --- a/nlesc_specific/checklist/checklist_prototype.md +++ /dev/null @@ -1,41 +0,0 @@ -# Checkmatrix for software projects. - -Printable check-list -- complete this checklist to ensure your project is in good shape. - - -## Version Control - - -Item / Phase | Done | -:------------|:---------:| -use git as version control system (vcs)| -public vcs repository ([github](https://github.com/))| -meaningful commit messages| - - -## Licensing - -Item / Phase | Done | -:------------|:---------:| -[Apache 2 license](http://www.apache.org/licenses/LICENSE-2.0)| -compatible license of all libraries| -`NOTICE(.txt or .md)` listing licenses, request citation of paper if applicable| - -## Communication - -Item / Phase | Done | -:------------|:---------:| -project discussion list (github issues, mailing list, not private email) for all project related discussions from the beginning of the project| - -## Documentation - -Item / Phase | Done | -:------------|:---------:| -`README.md` - clear explanation of the goal of the project with pointers to other documentation resources. Use [GitHub flavored markdown](https://help.github.com/categories/writing-on-github) for, e.g., [syntax highlighting](https://help.github.com/articles/creating-and-highlighting-code-blocks).| - -## Use standards - -Item / Phase | Done | -:------------|:---------:| -exchange format (Unicode, W3C, OGN, NetCDF, etc)| -protocols (HTTP, TCP, TLS, etc)| diff --git a/nlesc_specific/checklist_matrix.md b/nlesc_specific/checklist_matrix.md deleted file mode 100644 index cb70a27e..00000000 --- a/nlesc_specific/checklist_matrix.md +++ /dev/null @@ -1,109 +0,0 @@ -# Checkmatrix for software projects. - -This matrix shows what parts of the software sustainability checklist should be taken care of at (perhaps slightly before) what state of a project. - -Though very generic in scope and context, this is an eScience Center specific list. This allows us to keep the number of "states" low. - -## Explanation of project states - -- [*Prototype phase*](checklist/checklist_prototype.md). The first step in most software development is trying out different things with no intention in keeping the intermediate results. Signs you could be in this phase: - - You switch programming languages. - - You throw away all of your code once in a while - - You work on the code by yourself - - You are waiting with showing other people your code until you "clean it up a bit first". -- [*Pre-release phase*](checklist/checklist_prerelease.md). Eventually you get software you intend to keep. Signs you could be in this phase: - - You have multiple developers. - - You have external contributors. - - You are working up to a release. - - Users ask you if the software is done yet. -- [*Maturity phase*](checklist/checklist_mature.md): Software that has reached maturity, has a clear function and scope, and is used. Signs you could be in this phase: - - The software has a release. - - The software has users: people actually using your software/code - - You have external contributor - - The software is actively used and contributed to by many people. - -These states happen in order and are exclusive. - -## Version Control - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -use git as version control system (vcs)|X|| -use [GitHub flow branching model](https://guides.github.com/introduction/flow/) (use feature branches and pull requests)||X| -public vcs repository ([github](https://github.com/))|X|| -meaningful commit messages|X|| - - -## Releases - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -[semantic versioning](http://semver.org/)|||X -tagged releases ([github releases](https://help.github.com/categories/releases/))|||X -CHANGELOG.md ([Keep a CHANGELOG](http://keepachangelog.com/))|||X -one command install ([pip](https://pypi.python.org/pypi/pip), [npm](https://www.npmjs.com/package/npm) etc)|||X -package in package manager ([pypi](https://pypi.python.org/pypi), [npm](https://www.npmjs.com/) etc)|||X -discuss release cycle with coordinator||X| -release quick-scan by other engineer (is documentation understandable, can it be installed, etc)|||X -notify our Communications Advisor for dissemination (news item on site / annual report, etc)|||X - -## Licensing - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -[Apache 2 license](http://www.apache.org/licenses/LICENSE-2.0)|X|| -compatible license of all libraries|X|| -`NOTICE(.txt or .md)` listing licenses, request citation of paper if applicable|X|| - -## Communication - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -home page with all the necessary introduction information, links to documenation, source code (github) and latest release download (eg. [github.io pages](https://pages.github.com/))|||X -project discussion list (github issues, mailing list, not private email) for all project related discussions from the beginning of the project|X|| -for services: a demo docker image in dockerhub (with Dockerfile)|||X -for websites: an online demo|||X -Pitch presentation (1 to 3 slides)||X| - -## Testing - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -[unit tests](https://en.wikipedia.org/wiki/Unit_testing)||X| -build tests||X| -[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration), using a [publicly available service](../best_practices/testing.md#Online-services-for-continuous-integration)||X| -continuous code coverage and code quality metrics public, minimum 70% coverage required|||X -end2end test for (web) user interfaces|||X -track dependencies (with [Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates)) or other service depending on codebase language)|||X - -## Documentation - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -`README.md` - clear explanation of the goal of the project with pointers to other documentation resources. Use [GitHub flavored markdown](https://help.github.com/categories/writing-on-github) for, e.g., [syntax highlighting](https://help.github.com/articles/creating-and-highlighting-code-blocks).|X|| -well defined functionality||X| -source code documentation||X| -usage documentation||X| -documented development setup (good example is [Getting started with khmer development](http://khmer.readthedocs.org/en/latest/dev/getting-started.html))||X| -contribution guidelines [example](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)||X| -code of conduct ([contributor covenant](http://contributor-covenant.org/))||X| -documented code style||X| -meaning of issue labels used||X| -DOI or PID ([making your code citable](https://guides.github.com/activities/citable-code/))|||X - - -## Development setup - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -using the eScience Center coding style is required||X| -[editorconfig](http://editorconfig.org/)||X| -applied code style in automated way if possible (i.e using linters and code formaters)||X| -dev environment docker images in Dockerhub (with Dockerfile)||X| - -## Use standards - -Item / Phase | Prototype | Pre-release | Mature | -:------------|:---------:|:-----------:|:------:| -exchange format (Unicode, W3C, OGN, NetCDF, etc)|X|| -protocols (HTTP, TCP, TLS, etc)|X||