Best practices details & SMP elements
In addition to categorizing FAIR4RS principles and best practices for FOSS development according to the FAIR principles, these principles can also be organized by software implementation categories. Each category can then be expanded to outline specific components and their respective best practices in greater detail.
This section outlines the categories and components mentioned, each of the latter corresponding to an entry in an SMP. For each element, we
- Indicate the FAIR4RS principles and/or best practices it addresses;
- Include a brief description of the element for guidance in implementing the best practices;
- Provide example content that can be included in the SMP. When an exemplary response to a best practice is available for an SMP element, it is labeled as "Good answer (v0)" for the initial version (before development) and "Good answer (later versions)" for subsequent versions (during and after development);
- Provide links to resources to learn more about relevant best practices (for applicable elements).
General management
Title
β³ [BR2]
Provide a clear, descriptive title for the software project. It should be unique, recognizable, and informative.
Purpose
β³ [BI1, R3, BR2]
Provide general information such as: what problem does it solve, who is the intended audience, what are its advantages and limitations, etc.. Explain why developing new software is necessary. New software should not be developed when it would be more cost-efficient and beneficial for the overall community to contribute to existing software.
Risk analysis
β³ [R3]
Describe the main external factors that should be considered by developers and users of the software. For example, compliance with privacy policies, security considerations, reliability requirements, portability / vendor lock, etc..
π Resources:
| Resource | Description |
|---|---|
| OWASP Top Ten | The top ten security risks for web applications and prevention suggestions |
| The Turing Way guide on Risk assessment: complexity and impact | Explanation of the risk matrix and measuring complexity and impact |
| How to Perform a Software Risk Assessment? | A guide on how to perform a software risk assessment (on generic software) |
| Risk Analysis Tools for Managing Software Projects (2018) by RankoviΔ and Ivanovic | A paper with comparative analysis of the 4 types of different risk management tools |
Maintainers
β³ [R1.2, BR2]
List the names and contact information of the software maintainers (at least two people). The maintainers are responsible for the software's development, maintenance, and support.
π’ Good answer (v0 + later versions):
Primary maintainer: <name + contact>,
other maintainers: <names + contacts>
Support and resources during development
How do you plan to procure development and long term maintenance of your software? Plan resources for support-related activities such as training, hiring research software engineers, infrastructure, hardware, etc.. The level of support should be in line with promises made regarding the level of service provided by your software.
Maintenance plan
β³ [A2, R3, BR6]
How do you plan to procure long term maintenance of your software? What level of support will be provided for users of the software and how will this support be organised? Make sure there are arrangements in place for the maintenance and reuse of your software.
Retirement plan
β³ [A2]
Describe how the software will be retired, including how users will be informed and how data will be handled. Include a plan for archiving the software and its documentation. Specify the expected end-of-life date for the software. If the software is to be maintained indefinitely, explain how this will be ensured.
Licensing & accessibility
Repository
β³ [A1, BA1, R1.2]
Describe where the software will be stored and whether it will be publicly available. If you do not plan to make it publicly available you should provide a justification.
π’ Good answer (v0):
The software will be stored in a <public or private> GitHub (or Gitlab) repository
π’ Good answer (later versions):
<link to a GitHub (or GitLab) repository>
Metadata
TODO
Registries
β³ [F4, BF2, A1, R1.2]
List relevant software registries where the software will be findable.
π’ Good answer (v0):
The software will be findable through the following relevant registries:
<registry links>
π’ Good answer (later versions):
<links to the software in the registries>
π Resources:
| Resource | Description |
|---|---|
| Awesome Research Software Registries | eScience Center's curated list of research software registries (organized by country, organization, language and domain + generic registries) |
Persistent identifier
β³ [F1, F3, BF1]
Specify the identifier system (e.g., DOI) to be used for versioning and citing the software.
π’ Good answer (v0):
The software will be assigned a DOI for each major release via <DOI issuing system/registry>
π’ Good answer (later versions):
<DOIs for each major release>
π Resources:
| Resource | Description |
|---|---|
| Digital Object Identifier (DOI) System | DOI system's official website |
| DataCite | support the creation and management of DOIs for research outputs |
Citation
β³ [BR2]
Describe how users should cite the software in publications or other projects. Specify if a CITATION.cff file or similar will be used.
π’ Good answer (v0):
The repository will include a CITATION.cff file
π’ Good answer (later versions):
<link to CITATION.cff>
π Resources:
| Resource | Description |
|---|---|
| The Turing Way guide on Software Citation with CITATION.cff | A guide on how to cite software and data in your research publications |
| CFF INIT | A tool to help you generate citation metadata and create CITATION.cff files for your software projects |
License
β³ [BA1, R1.1, BR4]
Specify the software license. The license should be as open as possible, and as closed as necessary. Recommended license: Apache 2.0
π’ Good answer (v0):
The software will be licensed under the <preferably Apache 2.0> license,
and the repository will include a LICENSE file
π’ Good answer (later versions):
<Apache 2.0 or other license name> : <link to LICENSE>
π Resources:
| Resource | Description |
|---|---|
| No License | Explanation for what happens when you don't use a license |
| Free Software Foundation (FSF) Licensing & Compliance Team | Licensing recommendations, analysis, and FAQ |
| The Turing Way guide on licensing | Explains how important it is to understand how laws and licensing can affect your project |
| Public License Selector | A quiz to help you choose a license for your project |
| ChooseALicense.com | A website to help you choose an open source license for your project |
| tl;dr Legal | A website that explains software licenses in plain English |
| eScience Center guide on sharing software | A guide on how to share software and data legally and ethically |
License compatibility
β³ [R1.1, BR4]
Does your software respect the licences of dependencies it uses? How will you check that?
π’ Good answer (v0):
The software license will respect the licenses of all its dependencies.
We will check that by < >
π’ Good answer (later versions):
The software license respects the licenses of all its dependencies
π Resources:
| Resource | Description |
|---|---|
| The Turing Way guide on License Compatibility | A guide on how to checking if licenses are compatible with each other, including a permissions overview matrix |
| Various Licenses and Comments about Them | A list of various licenses and information on compatibility and whether they qualify as FS and copyleft and compatibility |
Documentation
π Resources:
| Resource | Description |
|---|---|
| Write the Docs' guide on Software documentation | Community wisdom on best practices for creating software documentation |
| Sphinx | A tool that makes it easy to create intelligent documentation (including API reference) using reStructuredText or MyST Markdown for various languages. |
| MkDocs | A fast and simple static site generator that's geared towards building project documentation using Markdown. |
| Redoc | An open-source documentation tool that generates API documentation from OpenAPI definitions. |
User documentation
β³ [R1, BR2, BR6]
How will your software be documented for users?
π’ Good answer (v0):
The user documentation will provide step-by-step installation, configuration, and usage instructions
It will also include a tutorial to guide new users and input/output examples to demonstrate typical use cases
π’ Good answer (later versions):
<link to user documentation>
Deployment documentation
β³ [R1, BR2]
How will you document the installation requirements of your software?
π’ Good answer (v0):
The deployment documentation will outline system requirements, dependencies, and setup instructions for supported environments
It will also cover configuration steps and include detailed system requirements to ensure successful installation and deployment
π’ Good answer (later versions):
<link to deployment documentation>
Developer documentation
β³ [R1, BR2, BR5]
How will your software be documented for future developers?
π’ Good answer (v0):
The developer documentation will include an overview of the code structure and content
It will also provide an API reference, contributing guidelines, and a code of conduct to support collaboration and maintain code quality
π’ Good answer (later versions):
<link to developer documentation>
API documentation
β³ [BI3, R1, BR2]
How will you document functions or endpoints, and what format will be used (e.g., Sphinx, Swagger)?
π’ Good answer (v0):
We will create an API reference using <Sphinx or some other tool>
π’ Good answer (later versions):
The API reference is included in the Developer documentation
Docstring/comments in the source code
β³ [BI3, R1, BR2]
Will the source code include docstrings and comments?
π’ Good answer (v0):
The source code will include in-line comments and docstrings
π’ Good answer (later versions):
The source code includes docstrings and in-line comments
Tutorial
β³ [R1, BR2]
Will you include a tutorial? If so, provide a summary of what it will cover.
π’ Good answer (v0):
We will provide a basic tutorial to get users started with setup, configuration, and sample runs
The tutorial will be included in the User documentation
π’ Good answer (later versions):
The tutorial is included in the User documentation
Contributing guidelines
β³ [R1.2, BR2, BR5]
Will you include guidelines for contributing to the software? If so, provide a summary of what they will cover.
π’ Good answer (v0):
The repository will include a CONTRIBUTING file with instructions for code submissions,
including <(e.g., coding standards, testing requirements)>
The contributing guidelines will be included in the Developer documentation
π’ Good answer (later versions):
<link to CONTRIBUTING file>
The contributing guidelines are included in the Developer documentation
π Resources:
| Resource | Description |
|---|---|
| Setting guidelines for repository contributors (GitHub) | GitHub's instructions on including contributing guidelines to a repository |
Code of conduct
β³ [BR2, BR5]
Will you include a code of conduct for contributors with standards for how to engage in a community? If so, provide a summary of what it will cover.
π’ Good answer (v0):
The repository will include a CODE_OF_CONDUCT file with contributor behavior standards,
adopted from <Contributor Covenant v2.1 or other templates>
The code of conduct will be included in the Developer documentation
π’ Good answer (later versions):
<link to CODE_OF_CONDUCT file>
The code of conduct is included in the Developer documentation
π Resources:
| Resource | Description |
|---|---|
| Adding a code of conduct to your project (GitHub) | GitHub's instructions on adding a code of conduct along with accessing templates |
| Contributor Covenant | A code of conduct template for open source projects |
Changelog
β³ [F1.2, BF1, R1.2, BR2]
Will you include a changelog? If so, explain how version updates and changes will be tracked and note any specific format used
π’ Good answer (v0):
The repository will include a CHANGELOG file with all release details and patch notes
π’ Good answer (later versions):
<link to CHANGELOG file>
π Resources:
| Resource | Description |
|---|---|
| Keep a changelog | Style guide for changelogs |
| Common changelog | Adapted from and a stricter subset of "Keep a changelog" (resource above) |
| A Beginnerβs Guide to Git β What is a Changelog and How to Generate it | A guide on how to generate a changelog using Git |
Release notes
β³ [F1.2, BF1, R1.2, BR2]
Describe what information will be included in each release note, such as new features, fixes, and known issues
π’ Good answer (v0):
The release notes will list version features, fixes, known issues, and improvements
π’ Good answer (later versions):
The release notes are included in the [Software Releases](#software-releases)
π Resources:
| Resource | Description |
|---|---|
| About releases (GitHub) | GitHub's info on releases along with managing, creating, and automating them |
Bug reporting & feature request
β³ [BR5, BR6]
Outline the process for reporting bugs or requesting features, including where users can submit these and any templates to guide their input
π’ Good answer (v0):
We will use GitHub (or Gitlab) issues with templates
π’ Good answer (later versions):
<link to the Issues>
π Resources:
| Resource | Description |
|---|---|
| About issues (GitHub) | GitHub's info on issues along with configuring, using, and administering them |
| Configuring issue templates for your repository (GitHub) | GitHub's instructions on creating and configuring issue templates |
Testing & quality assurance
π Resources:
| Resource | Description |
|---|---|
| The Turing Way guide on good practice for testing | General guidance that applies to all types of testing |
| The Practical Test Pyramid | A guide on how to structure your tests for maximum efficiency and effectiveness with practical examples |
| Testing with pytest. Unit, Integration and Smoke tests. (Python) | A guide on how to use pytest for testing your Python software |
Smoke tests
β³ [R3, BR3]
How will you make sure that critical parts of the software work? Describe which parts of the software are most critical and will be covered by smoke tests to ensure they work as expected.
π’ Good answer (v0):
We will write smoke tests to ensure the critical parts of the software do not fail
π’ Good answer (later versions):
<link to smoke tests>
Utility tests / doctests
β³ [R3, BR2, BR3]
How will you show the expected working examples of components (functions, methods)?
π’ Good answer (v0):
We will create doctests in the documentation to show implementation examples
π’ Good answer (later versions):
The API reference includes the doctests
π Resources:
| Resource | Description |
|---|---|
| doctest β Test interactive Python examples | Official Python documentation on doctests |
Unit tests
β³ [R3, BR3]
How will you make sure components (functions, methods) of the software work as expected? Specify the core functions covered by unit tests and the framework or tools used. Mention integration with CI/CD if relevant.
π’ Good answer (v0):
We will create unit tests for core functions using <pytest or some other tool>
and link them to a CI/CD pipeline
π’ Good answer (later versions):
<link to unit tests>
The tests are linked to the CI/CD pipeline
Integration / system tests
β³ [R3, BR3]
How will you make sure that the combination of components and the software as a whole function as expected? Describe the scenarios covered by integration tests and how they validate that components work together properly. Mention integration with CI/CD if relevant.
π’ Good answer (v0):
We will create integration and system tests for the software using <pytest or some other tool>
and link them to a CI/CD pipeline
π’ Good answer (later versions):
<link to integration and system tests>
The tests are linked to the CI/CD pipeline
Regression tests
β³ [R3, BR3]
How will you make sure that new changes do not break existing functionality? Describe the scenarios covered by regression tests and how they validate that new changes do not break existing functionality. Mention integration with CI/CD if relevant.
π’ Good answer (v0):
We will create regression tests for the software using <pytest or some other tool>
and link them to a CI/CD pipeline
π’ Good answer (later versions):
<link to regression tests>
The tests are linked to the CI/CD pipeline
π Resources:
| Resource | Description |
|---|---|
| Plan your regression testing strategy by asking the relevant questions | A guide on how to plan your regression testing strategy |
Code quality standards
β³ [BI3, R3, BR3]
Do you follow specific software quality guidelines? If yes, which ones? Does your code adhere to relevant code quality standards (styling, modularity, etc.)?
π’ Good answer (v0):
We will follow <PEP 8 or some other standards> for code quality
π’ Good answer (later versions):
Code quality standards applied: <PEP 8 or some other standard>
π Resources:
| Resource | Description |
|---|---|
| OpenSSF Best Practices Badge Program | Self-certifying badge is a way for Free/Libre and Open Source Software projects to show that they follow best practices |
| Python Code Quality: Tools & Best Practices | A guide on how to improve the quality of your Python code |
| Stylized presentation: PEP 8 β the Style Guide for Python Code | A presentation of the Python Enhancement Proposal 8, which is the Style Guide for Python Code |
| PEP 8 β Style Guide for Python Code | The official Python Style Guide |
Linting
β³ [BI3, R3]
How will you ensure that the code is clean and follows best practices? Specify the tools used for linting and the rules enforced.
π’ Good answer (v0):
We will use <flake8 or some other tool> to lint the code and enforce <PEP 8 or quality standards> rules
π’ Good answer (later versions):
We use <flake8 or some other tool> to lint the code and enforce <PEP 8 or quality standards> rules
Sample data/parameters
β³ [R1, BR2]
Will you provide sample data or parameters for testing the software? If yes, describe the type of data or parameters that will be provided.
π’ Good answer (v0):
<Sample data / parameters> will be provided for testing basic functionality
π’ Good answer (later versions):
<link to sample data / parameters>
Interoperability
Programming languages
β³ [I1, BI3]
List the programming languages used and explain why each is included in the software.
π’ Good answer (v0):
The primary programming language will be <language> because <reason>
<If applicable, additional languages> will be used for <reason>
π’ Good answer (later versions):
The primary programming language is <language>
<If applicable, additional languages> are used for <roles>
Input formats
β³ [I1, BI3]
Describe the data input formats supported (e.g., JSON or CSV), and any requirements for structuring input data
π’ Good answer (v0):
The software will accept <common formats> formats
π’ Good answer (later versions):
The software accepts <common formats> formats
Output formats
β³ [I1, BI3]
Specify the output formats available (e.g., JSON or CSV)
π’ Good answer (v0):
The software will output <common formats> formats
π’ Good answer (later versions):
The software outputs <common formats> formats
Versioning & release management
Version control system
β³ [F1.1, F1.2, BF1, R1.2, R3]
Explain the version control system used and describe the approach to tagging releases and writing commit messages
π’ Good answer (v0):
Git; every change will be documented with "Conventional Commits" and version tags
π’ Good answer (later versions):
Git; every change is documented with "Conventional Commits" and version tags
π Resources:
| Resource | Description |
|---|---|
| Conventional Commits | A specification for adding human and machine readable meaning to commit messages |
Versioning scheme
β³ [F1.1, F1.2, BF1, BI3, R3]
Describe the chosen versioning scheme and how users can interpret version numbers
π’ Good answer (v0 + later versions):
Semantic: MAJOR.MINOR.PATCH
Reproducibility & reuse
Packaging
β³ [R3, BR1]
How will your software be packaged and distributed? Do you use appropriate package managers to allow users to install/deploy your software with ease?
π’ Good answer (v0):
The software will be packaged and distributed using <Conda or some other tool>
π’ Good answer (later versions):
<link to entry in a packaging registry>
π Resources:
| Resource | Description |
|---|---|
| The Turing Way guide on Package Management Systems - Conda | A guide on how to use Conda to install and keep track of the different software packages (and their versions) |
Software releases
β³ [BF1, R1.2, BR6]
How will you manage software releases and ensure that users can access previous versions? Outline the release strategy, including frequency, stability of each release, and channels where users can access releases. Describe how users can access previous versions of the software.
π’ Good answer (v0):
Releases will be tagged using <Git tags or other tools> and made available in the repository's Releases page with stable, beta, and archived versions
π’ Good answer (later versions):
<link to Releases>
Dependencies
β³ [I1, I2, BI1, BI2, R1, BR2]
Provide a detailed list of all dependencies, both language-specific and system-level, along with required versions and compatibility notes.
π’ Good answer (v0):
Language-specific dependencies : <libraries, packages, and frameworks with versions (e.g., numpy β₯ 2.1)>
System-level dependencies : <system tools and utilities with versions (e.g., OpenSSL β₯ 3.4)>
The dependencies will be detailed in the Deployment documentation
π’ Good answer (later versions):
The dependencies are detailed in the Deployment documentation
System requirements
β³ [BI2, R1, BR2]
Specify the hardware and operating system requirements necessary to run the software
π’ Good answer (v0):
Supported operating systems : macOS <version>+, Ubuntu <version>+, Windows <version>+
Special computing requirements : <special hardware or configuration requirements (e.g., GPU)>
Minimum processor requirements : <processor type>, <clock speed> GHz+
Minimum memory requirements : <RAM size> GB
Minimum storage requirements : <storage size> GB
The system requirements will be detailed in the Deployment documentation
π’ Good answer (later versions):
The system requirements are detailed in the Deployment documentation
Input/output examples
β³ [BR2]
Are you providing input/output examples to ensure reproducibility of your software?
π’ Good answer (v0):
We will provide input/output examples that cover <common use cases> for reproducibility
The examples will be included in the User documentation
π’ Good answer (later versions):
<link to input/output examples>
The examples are included in the User documentation