Skip to content

Latest commit

 

History

History
108 lines (92 loc) · 10.3 KB

best-practices-assessment.md

File metadata and controls

108 lines (92 loc) · 10.3 KB

Best practices assessment

1. Project Setup

  • 1.1. Work from GitHub with a GitHub repository dedicated to your software in the AI-READI organization
  • 1.2. Follow GitHub best practices
  • 1.3. Make the GitHub repository public from day one
  • 1.4. Choose a license and include a LICENSE file containing standard license terms in the root of your GitHub repository
    • 1.4.1. All software in the AI-READI project will be developed under the MIT license (unless exceptions)
  • 1.5. Add a README.md file in the root of your GitHub repository and include at least the following information as they become available
    • 1.5.1 Brief description of the software
    • 1.5.2 How to run the software (from the source code)
    • 1.5.3 Inputs and outputs of the software, if applicable
    • 1.5.4 Parameters, data, and data formats required to run the software, if applicable
    • 1.5.5 The standards followed during development
    • 1.5.6 How to report bugs/issues
    • 1.5.7 Acknowledgment of NIH funding support
    • 1.5.8 Other acknowledgments, if applicable
    • 1.5.9 Clear attribution for authorship and software dependencies
    • 1.5.10 Include shields.io badges at the top of your README to showcase the following: license, number of contributors, number of open issues, Zenodo DOI
    • 1.5.11 Include the AI-READI logo at the bottom of your README

2. Code development

  • 2.1. Follow language-specific standards and conventions when writing your code
  • 2.2. Use an appropriate linter for automated code quality improvements and formatting fixes
  • 2.3. Give functions and variables meaningful names
  • 2.4. Include comments within your code when deemed necessary for reuse.
  • 2.5. If using external libraries, favor well-maintained software libraries and make sure their license is compatible with your software license
  • 2.6. Record software dependencies in a requirements.txt or similar file
  • 2.7. Add appropriate tests (unit, integration, and end-to-end) to all modules in your application.
  • [ ]2.8. Identify and utilize tools to benchmark for accessibility such as Accessibility Insights for Web development etc.
  • 2.9. Web-based software should support Modern Browsers developed with the Webkit, Blink, or Gecko rendering engines (e.g. Chrome, Safari, Firefox, MS Edge).

3. Pushing changes to GitHub repository

  • 3.1. Use two branches for your software: main and dev.
  • 3.2. When committing a change to the repository, make sure the change reflects a single purpose (e.g. fixing a bug or adding a new feature)
  • 3.3. Use conventional commits
  • 3.4. Make sure your git commit hooks are always run before committing to the public repository.
  • 3.5. When merging changes to the dev branch, create a PR from the feature or bug fix branch and invite at least one other collaborator to review the changes.

4. Documenting

  • 4.1. If more details are required to run the software from the source code in addition to what is included in the "README.md" (c.f. section 1.4.2), include them in other markdown files and refer to them in the README.
  • 4.2. If the software contains a user interface, maintain user documentation of the interface and identify in your README where the user documentation is located
    • 4.2.1. Use the wiki of your GitHub repository for simple software
    • 4.2.2. Build and maintain a dedicated webpage for the documentation of more complex software.
  • 4.3. If your software includes an application programming interface (API), it must be documented separately as per API best practices.
  • 4.4. Include instructions for contributing to your software in a "CONTRIBUTING.md" file located at the root of your GitHub repository.
  • 4.5. Use GitHub issues to manage bugs/issues

5. Adding metadata

  • 5.1. Include metadata files:
    • 5.1.1. Include a codemeta.json file in the root of your GitHub repository. Provide at least the following information: Software name (name), Software description/abstract (description), Unique identifier (identifier), Authors (givenName, familyName) with their Organization name (affiliation), Keywords (keywords), Programming Language (programmingLanguage), First and current release date (datePublished and dateModified), License used (license)
    • 5.1.2. Include a CITATION.cff file in the root of your GitHub repository. Provide at least the following information: Authors (given-names, family-names) with their Organization name (affiliation), Software description/abstract (abstract), Unique identifier (identifiers), Keywords (keywords), License (license), Release date (date-released)

6. Version release

  • 6.1. Document changes between versions of your software in a "CHANGELOG.md" file located at the root of your GitHub repository
    • 6.1.1. Follow the Semantic Versioning 2.0 principles outlined here for version numbering
    • 6.1.2. Follow the "keep a changelog" guidelines for structuring your CHANGELOG file
  • 6.2. Make a GitHub release for each version of your software
    • 6.2.1. Use an automated git changelog builder based on conventional commits to document the changes for each release
  • 6.3. Deposit in a language-specific repository if available:
    • 6.3.1. Python packages: PyPI
    • 6.3.2. R packages: CRAN
    • 6.3.3. Docker-based tools: Dockstore
    • 6.3.4. JavaScript packages: npm
  • 6.4. Deposit in a domain-specific repository if available:
    • 6.4.1. Computational neuroscience models: ModelDB
    • 6.4.2. R-packages aimed at the analysis of genomics data: Bioconductor
  • 6.5. Deposit software on Zenodo:
    • 6.5.1. Include source code
    • 6.5.2. Include executable and other files necessary to run the software if applicable
  • 6.6. Share software on the bio.tools registry if the software could be of interest to the larger biomedical community outside the AI-READI project

7. Suggested automation tools/Developer experience

  • 7.1. Unless you have a preferred code editor, use VS Code for developing your code and include the .vscode directory in your GitHub repository.
  • 7.2. Use these VS Code extensions (or their equivalent in your preferred code editor) as applicable to your project to automatically implement some elements of the best practices:
    • 7.2.1. Better Comments: Help you create more human-friendly comments and visualize them in your code.
    • 7.2.2. ESLint: Integrates ESLint code formatting into VS Code for Javascript projects.
    • 7.2.3. Isort: A Visual Studio Code extension that provides import sorting for Python using isort.
    • 7.2.4. Prettier - Code formatter: Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary.
    • 7.2.5. TypeScript Vue Plugin (Volar): A TypeScript server plugin to make the TypeScript server know *.vue files.
  • 7.3. Use an appropriate linter for additional code quality checks before pushing a commit (eg: Flake/Black for Python, ESLint/Prettier for Javascript, etc.)
  • 7.4. When adding automated testing to your application try to use the following testing frameworks if possible:
    • 7.4.1. Javascript:
    • 7.4.2. Python:
      • 7.4.1.3. Unit/Integration - pytest
  • 7.5. Use GitHub actions to automate tasks such as fixing grammatical errors, formatting code, managing GitHub issue submission, stale issues, and PRs, running unit/integration or end-to-end tests, building and releasing app/api/documentation versions on GitHub and Zenodo.
  • 7.6. Use TypeScript for any web/Node.js applications instead of JavaScript where possible.
  • 7.7. Use Docusaurus for developing and maintaining simple hostable development and/or user documentation
  • 7.8. Use FAIRshare to create metadata files easily, make GitHub releases, share software files on Zenodo, and register the software on bio.tools
  • 7.9. Mirror repository on GitLab for backup. The AI-READI organization has GitLab sync automatically set up so no further actions are required

Additional Information

Use this file to assess your compliance with the best practices and to document any additional information that you would like to share with the AI-READI team. You may add any additional details to the checklist sections as needed.