Mandatory Exercise - Share your project openly

--- tags: seminar --- # Mandatory Exercise - Share your project openly In this lesson we’ll be looking at a critical piece of the development puzzle that builds on what we’ve learnt so far - sharing your software openly with others. ### The Levels of Software Reusability - Good Practice Revisited Let’s begin by taking a closer look at software reusability and what we want from it. Firstly, whilst we want to ensure our software is reusable by others, as well as ourselves, we should be clear what we mean by ‘reusable’. There are a number of definitions out there, but a helpful one written by [Benureau and Rougler in 2017](https://dx.doi.org/10.3389/fninf.2017.00069) offers the following levels by which software can be characterised: * **Re-runnable**: the code is simply executable and can be run again (but there are no guarantees beyond that) * **Repeatable**: the software will produce the same result more than once * **Reproducible**: published research results generated from the same version of the software can be generated again from the same input data * **Reusable**: easy to use, understand, and modify * **Replicable**: the software can act as an available reference for any ambiguity in the algorithmic descriptions made in the published article. That is, a new implementation can be created from the descriptions in the article that provide the same results as the original implementation, and that the original - or reference - implementation, can be used to clarify any ambiguity in those descriptions for the purposes of reimplementation Later levels imply the earlier ones. So what should we aim for? As researchers who develop software - or developers who write research software - we should be aiming for at least the fourth one: reusability. Reproducibility is required if we are to successfully claim that what we are doing when we write software fits within acceptable scientific practice, but it is also crucial that we can write software that can be understood and ideally modified by others. If others are unable to verify that a piece of software follows published algorithms, how can they be certain it is producing correct results? Where ‘others’, of course, can include a future version of ourselves. ### Instructions to make your project open Add essential components and files that make your software project instantly more openly available: #### 1. Deposit your project in a Open source code repository Choose a platform such as GitHub, GitLab, or Bitbucket to host your code repository. Create a new repository by adding a name and brief description for your project #### 2. Document Your Code using conventions (previous mandatory exercise) [Readable code](https://raw.githack.com/mwakok/FAIR4RS/main/Readability.html) and [in-code documentation](https://coderefinery.github.io/documentation/in-code-documentation/) are important parts in making your code easy to understand improving the readability of your code, you should consider: Writing code comments that explain the why of the code and not the what. Adding docstrings to (public) functions. Using common naming conventions (check a style guide). Adding whitelines and avoid compound statements. + **2.1.** Checkout a style guide for your Programming language and review your code for the readability considerations listed above. Ask yourself: *Would it make sense to adopt a style guide for your project? What conventions do you find useful?* + **2.2.** Following style guides can be made easy with a [linter](https://github.com/caramelomartins/awesome-linters). Review your code by running a linter (e.g. flake8 for Python, checkcode for MATLAB, IntelliSensefor C++, or lintr for R) to identify conflicts with the style guide. :::success **Extra exercices:** Check coderefinery modules: - [https://coderefinery.github.io/reproducible-research/](https://coderefinery.github.io/reproducible-research/) - [https://coderefinery.github.io/reproducible-research/organizing-projects/](https://coderefinery.github.io/reproducible-research/organizing-projects/) ::: #### 3. Write a READMEs Create a `README file` containing information about your project, installation instructions, and usage examples. You can include examples and tutorials demonstrating how to use your software for different tasks and scenarios. This helps others understand the capabilities of your software and, how to apply it to their own research. Numerous guidelines ([https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes), [https://www.makeareadme.com/](https://www.makeareadme.com/) )exist on how to write a good README file, but essentially the information to add: * Explain what the software does. There’s nothing more frustrating than downloading and installing something only to find out that it doesn’t do what you thought it did. * List required dependencies. * Provide compilation or installation instructions. * List all input and output files, even those considered self-explanatory. Link to specifications for standard formats and list the required fields and acceptable values in other files. If there is no rigorous definition for a format, explain its parts as clearly as possible in plain English. * List a few example commands to get a user started quickly. * State attributions and licensing. Attributions are how you credit your contributors; licenses dictate how others may use and need to credit your work. You can follow the [FAIR-CODE template](https://github.com/manuGil/fair-code/tree/main) #### 4. Add a LICENSE and CITATION file (previous exercise) Add a license and citation file to your first repository: - Add an open-source license to the repository. Use the Creative Common license tool to decide which license to use: https://chooser-beta.creativecommons.org - Check the GitHub documentation to know how to add a license file. Use this tool to generate a CITATION file and add it to your repository: https://citation-file-format.github.io/cff-initializer-javascript/#/ #### 5. Publish your research software with a DOI To get credit for the research software you produce, the best way is to publish it in a way that allows you to assign a Persistent Identifier (PID) such as a DOI (Digital Object Identifier) to the published version/release. For example: - Publishing your research software in a software journal ([you can see here a list of software journals](https://www.software.ac.uk/which-journals-should-i-publish-my-software)) - Publish your GitHub or GitLab repository through a data repository or archive that provides a DOI and makes the software citable. TU Delft offers [4TU.ResearchData](https://data.4tu.nl/portal), which has an integration with GitHub and GitLab to make the publication of research software easier. Other available software repositories [![Awesome](https://awesome.re/badge.svg)](https://awesome.re) found in: [Awesome Research Software Registries](https://github.com/NLeSC/awesome-research-software-registries) * [Research software directory]() * [4TUResearchData repository]() * [TUD]() * [Research Software Heritage]() * [Marven Central Repository]() * [Apache projects](https://projects.apache.org/) * [ORKG](https://orkg.org) * [Codewithpapers](https://paperswithcode.com/)