Workflow checklist

Overview

Teaching: 5 min
Exercises: 20 min
Duration: 0 min

Questions

• What will I do?

• When will I do it?

• How will I remember to?

Objectives

• Be confident you’ll remember to implement the skills learned here today.

How to use this checklist

• Copy the checklist to a new document.
• For each item, think about what it involves, and when you will do it.
• Consider how you might remind yourself to do it, or persuade yourself to make time for it.
• As you come up with your answers, write them in the space provided, or tick one of the existing suggestions.
  • The suggestions are roughly in the order of recommended best practice.
• When you’ve answered all the points in a section, tick it off.

Checklist

Licensing [ ]

• I will find out who will be the rights holder for the software
  • When I apply for funding
  • At the beginning of the project
  • When I put the code on a repository
  • When I make the repository public
  • When ………….. gets back to me, and I’ll chase them if they haven’t by ……………………………
  • ………………………………………………………………………………………………….
• I will decide on what license to apply to the software
  • When I’ve found out who the rights holder is
  • When I make the repository public
  • ………………………………………………………………………………………………….
• I will review the license applied to the software
  • When I add new dependencies
  • ………………………………………………………………………………………………….

Documentation [ ]

• I will write instructions for using the code
  • When I start to write code
  • When I put my code on a repository
  • ………………………………………………………………………………………………….
• I will document the code using
  • Recognised standard tools (e.g. Doxygen)
  • Separate documents
  • Inline comments
  • ………………………………………………………………………………………………….
• I will update the documentation
  • As I make changes to the code
  • _At a set time each day/week/month/…………………………………………………………………………………………………
  • Before I publish a new version
  • ………………………………………………………………………………………………….
• I will publish the documentation
  • Automatically using continuous integration
  • Whenever I publish a new version of the software
  • ………………………………………………………………………………………………….

Code [ ]

• I will make the code readable
  • As I write it
  • Once things are working like they should
  • Before I publish a new version
  • ………………………………………………………………………………………………….
• I will organise my files
  • Using a well-planned and clear directory structure
  • ………………………………………………………………………………………………….

Dependencies [ ]

• I will make sure my dependencies are listed
  • Using a full environment management system (e.g. Docker, Apptainer)
  • Using automated dependency management tools (e.g. conda, renv)
  • By automatically documenting them when the code runs
  • By including them in the documentation
  • ………………………………………………………………………………………………….
• I will review my dependency list
  • Automatically using dependency management tools
  • When I add or remove a dependency
  • Before I publish a new version
  • ………………………………………………………………………………………………….

Tests [ ]

• I will test my software
  • Using a testing framework (e.g. Cypress, pytest, testthat)
  • By having a set of things I do every time
  • ………………………………………………………………………………………………….
• I will run my software tests
  • Automatically using continuous integration
  • Before I push to the repository
  • Before I publish a new version
  • ………………………………………………………………………………………………….

Repository [ ]

• I will upload my code to
  • A dedicated code repository (e.g. GitHub)
  • A well-resourced repository (e.g. OSF, FigShare, Zenodo, university repositories)
  • A personal website
  • ………………………………………………………………………………………………….
• I will make the code publicly accessible
  • By enabling the approriate permissions in the repository
  • By publishing specific versions
  • ………………………………………………………………………………………………….

Publishing [ ]

• I will publish my code by
  • Issuing releases on a code repository
  • Ensuring the code repository is publicly accessible
  • ………………………………………………………………………………………………….
• I will do this
  • Whenever milestones are reached
  • Whenever I publish a related output (e.g. research paper)
  • Automatically whenever I push to the repository
  • ………………………………………………………………………………………………….

Referencing [ ]

• I will make my code citable by
  • Publishing specific releases with a DOI (e.g. via Zenodo)
  • Writing a technical/methods paper and submitting it to a journal
  • Citing specific releases directly
  • Citing the repository with a time/version stamp
  • Citing the repository only
  • ………………………………………………………………………………………………….
• I will do this
  • When I publish the code
  • When I publish a related output
  • ………………………………………………………………………………………………….

Collaboration [ ]

• I will make it easy for others collaborate on my code by (tick all that apply)
  • Using collaboration-friendly services like GitHub
  • Writing a welcome guide for new contributors
  • Having easy templates for users to submit bug reports and feature requests
  • Ensuring a welcoming attitude for contributors
  • ………………………………………………………………………………………………….
  • ………………………………………………………………………………………………….
  • ………………………………………………………………………………………………….
  • ………………………………………………………………………………………………….