# Program 3 design notes
[Table with program structure draft](https://tud365.sharepoint.com/:x:/r/sites/FAIRSupportTeam/_layouts/15/Doc.aspx?sourcedoc=%7BA54C5846-45D2-4341-933F-3FA412B613B1%7D&file=FAIR4RS-Program-Structure-Overview.ods&action=default&mobileredirect=true&DefaultItemOpen=1&ct=1700128596786&wdOrigin=OFFICECOM-WEB.START.REC&cid=eff59389-e5c3-4a37-b061-76e739d4b164&wdPreviousSessionSrc=HarmonyWeb&wdPreviousSession=6c5c32d5-82e0-43f2-859c-5a6cd9c8f185&wdLOR=c698857FB-385A-5B4F-B4AF-BDBE0A3767D7&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiI1MC8yNDEwMjAwMTMxNiJ9)

## Program design overview
Success criteria. Arrange a fixed time and place for people to join the program with clear and attainable exercises per session. (Not having this was one of the major reasons that influenced the low level of engagement from participants)

We do a flipped classroom, which essentially means that exercises are provided during the sessions and the participants are asked to go through them in pairs.

At the end there can be questions and overall discussion of the challenges or learnings.

### Overview of activities
A workout week is always followed by a Project week. In a workout week participants develop the same kind of exercises provided by us, using the coderefineries as a starting point. A project week provide exercises that are specific to each participants project.

## Program recommendations for applicants:
They point of this program is to learn how to apply good practices of FAIR. The selection and scope of a project can make this journey easy or impossible depending on the complexity of the project. This is why we recommend to select projects that are not too complex and ambituous, but rather well scoped and defined.
- Select a project that has potential for publication, for example, a code base that is an important part of a paper you are working towards.
- Select a project that you can license under an open source license.(Maybe here we can point to the TU Delft policy)
- Choose a python project if possible, this makes everything easier to learn.
- Consider starting a project from scratch if your current codebase is a dump of many different projects.Ideally select one aspect or element of this project.

## Detailed program (In progress)
# FAIR Program overview
- Intro
- Module 1: Basic Research Software Development. Basic of everythin important: version control, github, code structure, documentation, work environment.
- Module 2: Advanced Research Software Development. Advanced concepts of software development that can be applied in the context of research software inmediately and make your work more productive. Testing, automation, advanced templates? Advanced dependency management
- Module 3: Proof that your code is reproducible

# FAIR Program Detailed Design
### Week 1 Kickoff
- **Goals**: Discuss the FAIR process at TU Delft, from development to publishing.
- Guide and onboard participants on the approach to the Program.
- **Activities description**: Organizers introduce the goal of the program, participation guidelines, etc. They are also provided with exercises to work on and discuss in the second week seminar
- **Resources needed**: Room for kickoff, some snacks, Online educational resources and instructions to get started, Access to chat group
- **Date**:
**Notes**:
- We can recommend people to use vscode, and ideally setup github copilot as well.
- Now chatgpt is integrated in copilot and vscode and this is a game changer.
- The kickoff should include some concepts of Research Software including aspects of publishing, TU Delft policy etc.

---

## Module 1: Research Software Basics
**Rationale:** Without version control participants will struggle in modifying correctly their code.

### Workout week: Version Control
[In progress ]
#### **Goals**:
- Learn the basics of version control with git and github to get started in the program.

[Week 1- Instructions for Version control](/yeszmsBkT8eAnxrJYeSKIg)

#### **Activities description**:

- Participants are encouraged during 2 hours to go through the workshop material and do the exercises in pair.
- The goal of pairs is that participants can ask each other how they are doing. The session start with a quick introduction on the goal of the day. Participants are expected to ask questions during the session.
- At the end of the session, participants are expected to share their experience and discuss the exercises.

**Resources needed**: Selection of tutorials that touch upon the basics of version control with git and github.

**Date**:

**Notes**: Should we also decide on a development environment like vscode and copilot, etc? I think this can add a lot of value. Maybe copilot can be introduced in advanced software development practices, or code quality 2.

**References of tutorials and exercises**:
- [Git Intro](https://coderefinery.github.io/git-intro/)
- [eScience Center python template](https://github.com/NLeSC/python-template?tab=readme-ov-file#scenario-2-apply-to-pre-existing-code) We use this one and recommend people to start with this from the beggining, this should also show inmediately reproducibility concepts.

### Research code quality essentials I
**Rationale** Code is also documentation and design. In this week we focus on basic principles that allow developers to better reuse and operate code by simply adopting conventions in folder structure.

#### **Goals**:
- Provide a start on basics of code structure, code documentation and reusability.

#### **Activities description**:
- Exercise docstrings and use them
- Document dependencies
- Create a new branch and delect a folder structure for your project.
- Alternatively start from scratch

#### **Resources needed**:
- [In-code Documentation](https://coderefinery.github.io/documentation/in-code-documentation/)

**Date**:

**References**:

**Notes**
Maybe here we can demostrate already how following conventions yield results such as automatic documentation using sphinx.

**Examples**:
- [Do you speak python](https://github.com/wmvanvliet/gizmo?tab=readme-ov-file) Good way to introduce how to write tests. Maybe can be a good reference to build a more advanced exercise.
-
#### **To do**:
- [ ] Here we have to provide examples of code structure,
- [ ] Dependencies,
- [ ] Templates, etc.
- [ ]

### Project focused work
#### **Goals**:
- Adopt a code structure that adopts a convention. This could be even reusing a template. For example a python package template.
- Generate doc strings for the code you are writing using conventions
- Use python type hints to document your code

- **Activities description**:

- **Resources needed**:
- **Date**:
- **Notes**:

Checklist:
- Github repo accessible a otros colaboradores
- Dependencies
- Readme
- docstrings en un modulo
- Una estructura de carpetas

---

## Module 2: Adopting best practices of software development
(THIS MODULE NEEDS WORK)

**Rationale:** In this module we focus on the best practices of software development can be applied in the context of research software and inmediately benefit the participants. This can include testing, refactoring,

### Research code quality essentials II
(In progress)
#### **Goals**:
- Experience how to refactor code
- Testing, , make it cleaner,
- Better, testable, etc
- via a python example.
- **Activities description**:
- **Resources needed**:
- **Date**: May, 10th
**Notes**:
This could be more focused on actual software development for example including Pull requests, automated testing, refactoring concepts, reusable at another level, Snakemake, python and the terminal main scripts. Run the code in a different environment or machine, for example HPC could be a good exercise.
- It would be nice to show case how to go from acceptance criteria to

- **References**: [Modular Type-along](https://coderefinery.github.io/modular-type-along/), [Testing](https://coderefinery.github.io/testing/)

### Project focused on code quality essentials II
#### **Chalenges**:
- Setup collaborative testing environment in github using github actions.
- Develop tests for the code you are writing.
- Can you write a test a test before writing the code.

**Activities description**: Here week 3 and 4 are put in practice
**Resources needed**:
**Date**: April, 19th
**Notes**: Setup git and github repository to work in your project.

### Setting up a documentation website with sphinx
(I am not sure we need this one only for one session, perhaps this could follow the code documentation part, with automation)
- **Goals**: Prepare for the final presentation and work on the prioritized aspects of the project.
- **Activities description**:
- **Resources needed**:
- **Date**: May, 17th
- **Notes**:

### Reproducible Research
- **Goals**: The goal is to assist participants in making a plan to make their project more reproducible, FAIR, CODECHECK
- **Activities description**: In this week participants get more hands on coaching from DCC experts. At these point they are required to make a plan where they should define what are they going to deliver by the end of the program, phd, etc.
- **Resources needed**:
- **Date**: April, 5th
- **Notes**:

### Workout week focused on reproducible Research
- **Goals**: Learn core principles with simple example that illustrates the possibilities and important points of reproducibility
- **Activities description**: Participants have been provided the week before with instructions on what to do this week, they are expected to develop as much exercises as possible on the lesson provided. By the end of this week in the seminar they are expected to share and discuss what they did and how that applies to their specific case.
- **Resources needed**: Coderefinery lesson on reproducible research
- **Date**: March, 28th
- **Notes**:
- **References**: [Reproducible Research](https://coderefinery.github.io/reproducible-research/)

### Final presentations
- **Goals**:
- **Activities description**:
- **Resources needed**:
- **Date**: May, 24th
- **Notes**:

### Additional Dates
- **Date**: May, 31st
- **Notes**:

- **Date**: June, 7th
- **Notes**:

- **Date**: June 14th
- **Notes**:

---

# Raúl's bit (to be merged with above)

Main points:

- 3 blocks (Jose's modules)
- 9 weeks
- 2-hour sessions, at least half is on **own work**; No workout exclusive weeks

**TODO:**
- add preparation weeks in calendar (open call, close call, ...)
- add Learning outcomes , check https://elixir-europe-training.github.io/ELIXIR-TrP-FAIR-training-handbook/
- optional, design evaluation based on learning outcomes
- post-programme: publish materials (get a DOI, deposit in 4TU or TeSS-like repository https://tess.elixir-europe.org/)

# Schedule

| **Week** | **Date** | **Date Notes** | **Name** | |
| -------- | ---------| -------------- | ------------------------------------------------------------------------- | - |
| BLOCK 1 | | | | |
| 01 | 06/03/25 | | [Kickoff](#1-kickoff) | |
| 02 | 13/03/25 | | [Reproducible research software I](#2-reproducible-research-software-i) | |
| 03 | 20/03/25 | Code Refinery | [Code Development](#3-code-development) | |
| BLOCK 2 | | | | |
| 04 | 27/03/25 | | [Reproducible research software II](#4-reproducible-research-software-ii) | |
| 05 | 03/04/25 | | [Testing](#5-testing) | |
| 06 | 10/04/25 | | [Open software](#6-open-software) | |
| BLOCK 3 | | | | |
| 07 | 17/04/25 | Good Friday | [Version control II](#8-version-control-ii) | |
| 08 | 24/04/25 | Easter Monday | [CODECHECK](#9-codecheck) | |
| 09 | 01/05/25 | S Carpentry W | [Final Presentations](#10-final-presentations) | |
| -------- | ---------| -------------- | ------------------------------------------------------------------------- | - |

## BLOCK 1
### 1. Kickoff
- [10 mins] Program overview
- [10 mins] FAIR in the context of the software development cycle and research publication process
- [10 mins] [Project (folder) organization](https://coderefinery.github.io/reproducible-research/organizing-projects/)
- [10 mins] [Explore template(s)](https://coderefinery.github.io/reproducible-research/organizing-projects/#some-tools-and-templates)
- [10 mins] Explore examples of research software
- [10 mins] Journals
- [10 mins] Archives (4TU etc)
- [~ 50 mins] Start filling templates

### 2. Reproducible research software I
- [20 mins] [Introduction to version control with Git](https://coderefinery.github.io/git-intro/)
- Getting started
- Motivation
- Introduce repo with temperature calculations?
- [20 mins] Development setup
- Integrated Development Environments (IDEs)
- VScode, Spyder(?)
- Configuring Git command line and editor
- Fresh install walktrough
- [20 mins] Working on existing projects
- Browse an existing project
- Cloning a Git repository (template) and working locally
- Committing changes
- Merging changes and contributing to the project

- [60 mins] **Own project work**
- Setup an IDE
- Clone a template
- Fill out the template with own research

### 3. Code quality (Code Refinery Week)
- [20 mins] [Modular code development](https://coderefinery.github.io/modular-type-along/)
- [20 mins] [Documentation](https://coderefinery.github.io/documentation/)
- In-line comments, docstrings

- [80 mins] **Own project work**
- Modularize code
- Split long scripts (if available) into modules
- Document modules
- Focus on docstrings

## BLOCK 2
### 4. Reproducible research software II
- [20 mins] [Dependencies](https://coderefinery.github.io/reproducible-research/dependencies/)
- packages, other software
- [20 mins] [Environments](https://coderefinery.github.io/reproducible-research/environments/)
- venv, poetry, conda

- [80 mins] **Own project work**
- Identify dependencies
- Setup an enviroment
- Produce and environment file
- requirements.txt, yaml, toml

### 5. Testing
- [30 mins] [Testing](https://coderefinery.github.io/testing/)
- Testing locally
- Assertions, pytest
- Automated testing
- GitHub continuous integration

- [90 mins] **Own project work**
- setup pytest
- write at least one test
- setup at least one test on github

### 6. Open software
- [20 mins] [Documentation](https://coderefinery.github.io/documentation/)
- README, CONTRIBUTING
- Sphinx...
- [40 mins] **Own project work**
- Write a README
- Setup Sphinx and verify integration with documentation exercises

- [20 mins] Licensing, deposition/archiving, citation
- https://coderefinery.github.io/social-coding/software-licensing/
- https://coderefinery.github.io/social-coding/software-citation/
- https://coderefinery.github.io/social-coding/sharing-data/
- [40 mins] **Own project work**
- Choose and set a license
- Make a release
- Deposit release in zenodo sandbox
- get citation

## BLOCK 3
### 7. Version control II
- [20 mins] Interoperability (run elsewhere)
- [20 mins] **Own project work**
- VMs/VPSs or HPC

- [20 mins] Collaborating within the same repository
- [20 mins] **Own project work**
- (in pairs) invite classmate to your repo, work on it

- [20 mins] Collaborating with someone else's repository
- [20 mins] **Own project work**
- (in pairs) fork classmate repo, generate pull request

### 8. CODECHECK
- [30 mins] Basics of CODECHECK initiative
- codecheckR install

- [90 mins] **Own project work**
- (in pairs) draft a codecheck certificate for each other

### 9. Final Presentations