Update software checklist

docs/community/maintainers.md

@@ -17,7 +17,7 @@ _This content is automatically generated, all changes made will be lost._
 | infrastructure | Request VPS                               | Ashley Cryan          |                     |
 | infrastructure | Set up an Apache web server               | Ashley Cryan          |                     |
 | resources      | Curriculum                                | Ashley Cryan          | Maurits Kok         |
-| software       | FAIR checklist                            | Maurits Kok           |                     |
+| software       | FAIR4RS checklist                         | Maurits Kok           | Elviss Dvinskis     |
 | software       | Software Management Plan                  | Maurits Kok           |                     |
 | software       | Branch management                         | Maurits Kok           |                     |
 | testing        | Testing with MATLAB                       | Maurits Kok           |                     |

docs/software/checklist.md

@@ -1,100 +1,134 @@
 ---
 section: software
-title: FAIR checklist
+title: FAIR4RS checklist
 author_1: Maurits Kok
-author_2: 
+author_2: Elviss Dvinskis
 ---
 
-# FAIR software checklist
+# FAIR checklist for research software
 
-To ensure your research software is findable and usable by other researchers, we have compiled a checklist to improve its FAIRness (Findable, Accessible, Interoperable, Reusable).
+The goal of the FAIR principles is to improve research transparency, reproducibility and reusability. To achieve this, your research needs to be described through metadata, should be open for inspection, well-documented, and well structured. This ensures that it can be replicated, expanded upon, merged, reinterpreted, or reimplemented. The acronym FAIR stands for:
 
+- **F**indable: Your research software can be easily found (i.e. has rich metadata, unique identifiers).
+- **A**ccessible: Once found, it can be accessed, ideally through well-defined and open protocols.
+- **I**nteroperable: Your research is compatible with other datasets, tools, and workflows, allowing for integration and reuse across various applications and fields.
+- **R**eusable: The ultimate goal is that your research outputs can be reused in different contexts. This requires comprehensive documentation, clear licensing, and a modular structure.
 
-## Checklist
+While originally targetting data management, the FAIR for Research Software (FAIR4RS) extends these principles to research software, which, unlike data, is executable and evolves over time. Ensuring the findability of software involves metadata, identifiers, and version control systems, while accessibility includes guidelines for obtaining, installing, and running the software. Interoperability involves adherence to community-driven standards or protocols, and reusability requires detailed documentation and user guides to effectively apply the software in new research projects.
 
-The checklist below is in part based on the checklist provided by the [eScience Center](https://guide.esciencecenter.nl/#/nlesc_specific/checklist_matrix), licensed under CC BY 4.0.
+:::{seealso}
 
-### Version Control  
-_Essential_  
+- [FAIR Guiding Principles for scientific data management and stewardship to research software](https://zenodo.org/records/6623556)
+- [FAIR4RS community in Zenodo](https://zenodo.org/communities/fair4rs/records?q=&l=list&p=1&s=10&sort=newest)
+- [FAIR Software Checklist](https://fair-software.nl/) - five recommendations for FAIR (scientific) software 
+:::
+
+
+## Checklist
+
+:::{admonition} Version Control  
+_Essential_
 - [ ] Use [git](https://www.atlassian.com/git) as a version control system 
 - [ ] Upload your project on [GitHub](https://github.com/) or [TU Delft GitLab](https://gitlab.tudelft.nl/)
 
 _Recommended_  
 - [ ] Make your repository [public](https://coderefinery.github.io/social-coding/)
-- [ ] [Branch hygiene](https://coderefinery.github.io/git-branch-design/)
-- [ ] Use a branching model ([GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow))
-- [ ] [Meaningful commit messages](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [ ] Consider your [branch hygiene](https://coderefinery.github.io/git-branch-design/)
+- [ ] Use a branching model (e.g. [GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow))
+- [ ] Use [meaningful commit messages](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+:::
 
+:::{admonition} Collaboration
+_Essential_  
+- [ ] Make use of [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues)
 
-### Documentation - Repository
+_Recommended_
+- [ ] [Contribution guidelines](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
+- [ ] [Code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)
+
+:::
+
+:::{admonition} Project documentation
 _Essential_  
-- [ ] [README](https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md)
-- [ ] [LICENSE](https://doi.org/10.5281/zenodo.4629662)
+- [ ] [README](https://www.makeareadme.com)
+- [ ] Apply a TU Delft pre-approved [LICENSE](https://zenodo.org/records/4629635)
 - [ ] [CITATION](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)
 
+:::
 
-_Recommended_  
-- [ ] Make use of [Github issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues)
-- [ ] Contribution [guidelines](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
-- [ ] [Code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)
-
-### Documentation - Software
+:::{admonition} Software documentation
 _Essential_  
 - [ ] Source code documentation ([docstrings](https://numpydoc.readthedocs.io/en/latest/format.html))
+- [ ] Document your project dependencies
 - [ ] Installation instructions
-- [ ] Usage documentation
-- [ ] Developer setup
+- [ ] User documentation
 
 _Recommended_  
-- [ ] Examples and tutorials (Jupyter notebooks, videos, screencasts)
-- [ ] Website ([github.io pages](https://pages.github.com/), [Readthedocs](https://readthedocs.org/), [JupyterBook](https://jupyterbook.org/intro.html)
-- [ ] Build [API reference](https://developer.lsst.io/python/numpydoc.html) from docstrings
+- [ ] Developer documentation and setup
+- [ ] Examples and tutorials (e.g. Jupyter Notebooks)
 
+_Optional_
+- [ ] Documentation tools ([Sphinx](https://coderefinery.github.io/documentation/sphinx/), [JupyterBook](https://jupyterbook.org/intro.html), [Quarto](https://quarto.org/docs/guide/))
+- [ ] Build an [API reference](https://developer.lsst.io/python/numpydoc.html) from docstrings
+- [ ] Hosting ([GitHub Pages](https://pages.github.com/), [Readthedocs](https://readthedocs.org/))
+:::
 
-### Testing
-_Recommended_  
+:::{admonition} Software testing
+_Essential_
+- [ ] Installation/execution verification
+
+_Recommended_
 - [ ] [Defensive programming](https://swcarpentry.github.io/python-novice-inflammation/10-defensive.html)
 - [ ] Test your software with [integration tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-integrationtest.html) and [unit tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-unittest.html)
-- [ ] User installation test
-- [ ] Make use of [Continuous Integration](https://the-turing-way.netlify.app/reproducible-research/ci/ci-options.html)
-- [ ] Code coverage check ([Codecov](https://about.codecov.io/), [Sonarcloud](https://sonarcloud.io/), [Travis](https://www.travis-ci.com/))
-
+- [ ] Make use of [Continuous Integration](https://coderefinery.github.io/testing/continuous-integration/) to automate testing
 
-### Releases
-_Essential_  
-- [ ] Obtain a DOI ([Zenodo](https://zenodo.org/) or [4TU.ResearchData](https://data.4tu.nl/info/about-your-data/getting-started))
+_Optional_
+- [ ] Code coverage check (e.g. [Sonarcloud](https://sonarcloud.io/), [codecov](https://about.codecov.io))
+:::
 
-_Recommended_  
-- [ ] [Semantic versioning](https://semver.org/)
-- [ ] Tagged releases ([GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github))
-- [ ] [CHANGELOG](https://keepachangelog.com/en/1.0.0/)
-- [ ] Upload to registry ([PyPI](https://realpython.com/pypi-publish-python-package/), [conda](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/build-pkgs.html), [DockerHub](https://docs.docker.com/docker-hub/repos/))
-- [ ] [Release guide](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)
-- [ ] Continuous Integration for build and release
-
-### Code quality
+:::{admonition} Software quality
 _Essential_
-- [ ] Project [organisation](https://coderefinery.github.io/reproducible-research/organizing-projects/)
-- [ ] Record [software dependencies](https://coderefinery.github.io/reproducible-research/dependencies/)
+- [ ] [Organize](https://coderefinery.github.io/reproducible-research/organizing-projects/) your project for reproducibility
+- [ ] [Record and manage](https://coderefinery.github.io/reproducible-research/dependencies/) your software dependencies 
 
 _Recommended_
+- [ ] Make [refactoring](https://refactoring.guru/refactoring) part of your workflow
+- [ ] Follow [best coding practices](https://alan-turing-institute.github.io/rse-course/html/module07_construction_and_design/index.html)
+
+_Recommended for Python_
 - [ ] Follow [PEP8 guidelines](https://realpython.com/python-pep8/)
+- [ ] Use a tool for dependency management (e.g. [poetry](https://the-turing-way.netlify.app/reproducible-research/renv/renv-package.html))
 - [ ] Use linter (e.g. [pylint](https://pypi.org/project/pylint/), [flake8](https://pypi.org/project/flake8/))
-- [ ] Use a formatter (e.g. [black](https://github.com/psf/black), [yapf](https://github.com/google/yapf))
-- [ ] Follow [best coding practices](https://alan-turing-institute.github.io/rse-course/html/module07_construction_and_design/index.html)
+- [ ] Use a formatter (e.g. [black](https://github.com/psf/black))
+:::
+
+:::{admonition} Releases
+_Essential_  
+- [ ] Obtain a DOI ([Zenodo](https://zenodo.org/) or [4TU.ResearchData](https://data.4tu.nl/info/about-your-data/getting-started))
+
+_Recommended_  
+- [ ] Use [semantic versioning](https://semver.org/)
+- [ ] Create tagged releases ([GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github))
+- [ ] [CHANGELOG](https://keepachangelog.com/en/1.0.0/)
+- [ ] Upload to [registry](https://github.com/NLeSC/awesome-research-software-registries) (e.g. [PyPI](https://realpython.com/pypi-publish-python-package/), [conda](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/build-pkgs.html))
+- [ ] [Releasing guide](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)
 
-
+_Optional_
+- [ ] [Continuous Integration](https://the-turing-way.netlify.app/reproducible-research/ci/ci-options.html) for automated build and release
+:::
 
 ## Example repositories
 * [eScience Center - matchms](https://github.com/matchms/matchms) - Matchms is an open-source Python package to import, process, clean, and compare mass spectrometry data.
 * [TU Delft - Transposonmapper](https://github.com/SATAY-LL/Transposonmapper) - Transposonmapper is an open-source python package and Docker image for mapping transposons from sequencing data.
 
-## References
+:::{seealso}
+For more information on the principles behind FAIR software, please have a look at the following resources:
 
-For a full overview of the principles behind FAIR software, please have a look at the following resources:
+- [The Turing Way - Guide for Reproducible Research](https://the-turing-way.netlify.app/reproducible-research/reproducible-research.html) - general guide to reproducible research
+- [Towards FAIR principles for research software](https://content.iospress.com/articles/data-science/ds190026) - publication on the translation of FAIR principles for data to FAIR principles for software
+- [From FAIR research data toward FAIR and open research software](https://doi.org/10.1515/itit-2019-0040)
+- [FAIR Principles for Research Software](https://zenodo.org/records/6623556)
+:::
 
-* [FAIR software checklist](https://fair-software.nl/) - five recommendations for FAIR (scientific) software 
-* [Towards FAIR principles for research software](https://content.iospress.com/articles/data-science/ds190026) - publication on the translation of FAIR principles for data to FAIR principles for software.
-* [Guide for Reproducible Research](https://the-turing-way.netlify.app/reproducible-research/reproducible-research.html) - general guide to reproducible research
-* [The Zen of Scientific Computing](https://scicomp.aalto.fi/scicomp/zen-of-scicomp/#) - Scientific computing tips from Aalto University
-* [From FAIR research data toward FAIR and open research software](https://doi.org/10.1515/itit-2019-0040)
+## Acknowledgements
+The checklist was in part based on the checklist provided by the [eScience Center](https://guide.esciencecenter.nl/#/nlesc_specific/checklist_matrix), licensed under CC BY 4.0.