Github-Training-Repository

This repository is meant to be used to train new hires/volunteers on how to use Github. Reading the material and finishing the exercise should take around 6-8 hours. This all assumes that you are using Linux. If you are using Windows/Mac you will likely have to do additional steps to get things going.

Before you get started, please check that your actual name is visible on your Github profile. This way we know which account belongs to whom and when we make repositories citable your real name will be used and not your nickname.

Also, if you read this and you are not yet part of the ALLFED group on Github, please let Florian know your account name, so it can be added. General info: If a repository in the ALLFED group is private, there is a high chance it is not in use anymore. Please check in with the owner before trying to run it.

Preparation Material

Please look at all those materials before you start the exercise.

• Good enough practices in scientific computing: This gives a good overview of why we need to adhere to good coding practices and what the general idea is
• Good Research Code Handbook: Explanation of how to implement good coding practices in Python
• Fundamentals of Git and Github
• How to use Github with Github Desktop
• Getting started with anaconda and conda (if you feel like conda is too slow, check out mamba instead)
• ALLFED Repository Template Readme
• Overview of Python
• Automated Testing
• ChatGPT is pretty good at answering programming questions
• Data Visualization Crimes: please avoid those common mistakes when making plots
• The Seaweed Growth Model Repository can be seen as an example of how ALLFED repositories should look like. You can check how things are done there, if something here confuses you

Exercise

1. Fork this repository
2. Clone it to your local computer
3. Recreate the folder structure as described in the ALLFED Guidelines
4. Create a local virtual environment for the repository
   • When you try to install/change things make sure are activating it first!. If something related to virtual environments isn't working, always make sure that it is really activated.
5. Create two files in the src folder: numerical.py and plotting.py
6. Write a function in numerical.py that takes at least one argument and returns a numerical value
7. Write a function in plotting.py that creates a scatter plot and uses the ALLFED Style Sheet
8. Make your repository an installable package as described in Good Research Code Handbook
9. Add a Jupyter Notebook in your scripts folder and import numerical.py and call it
10. Write two test for numerical.py
11. Make sure that the documenation of all code follows the ALLFED Guidelines
    • If you set-up automated documentation, you can see the status in the pages setting
12. Automate the tests, so they run on every commit (you can just copy the files needed for that from the template
    • The files used for testing in Github Actions are hidden files. You might need to change the settings of your operation system to show you the hidden files.
    • you can play around with pytest in your terminal in VS Code
13. Create an environment.yml that specifies how your virtual environment can be recreated and save it in the repository
14. Send back a pull request, so we know you have finished this training
15. Check back in with Morgan or Florian if you have any questions ([email protected] or [email protected])

If you get stuck at any point please reach out to one of the data scientists (either [email protected] or [email protected]).