Conveners: Ishan Mishra, Ryan Petersburg, Bastien Brugger
Coding makes up a significant part of a researcher’s time, yet scientists are known to have kept bad habits from early days of programming. The modern open-source community has developed tools and good practices for making software available and maintainable, useful for the reproducibility of studies required by scientific guidelines. This workshop will focus on GitHub, a code-hosting platform, to explain how version control systems work and can be used to improve the quality and quantity of programming among researchers. We will also go through other options offered by GitHub, such as creating your own website, and supplementary resources available within the open-source community.
| 9:00 - 10:15 | Topic |
|---|---|
| 15 min | 1. Motivation for this workshop |
| 30 min | 2. How do Git & GitHub work: creating your account & first repo |
| 30 min | 3. Actual test project: fork repo, create new branch, edit files, pull request, merge |
| 10:15 - 10:45 | Break |
| 10:45 - 12:00 | Topic |
| 15 min | 4. Best practices for code accessibility and documentation |
| 30 min | 5. From a simple python script to a publishable package |
| 15 min | 6. Creating your website with GitHub Pages |
| 15 min | Discussion |
Parts 1 & 2: motivation and functioning (PDF)
- Merali (2010) Error… why scientific programming does not compute
- What is VCS? Git? GitHub? A small handbook to make things clear
- GitHub Glossary
- Guide to GitHub Flow
- Guide to Create your first repo
- List of GUI clients options
- Installing Git as command line for Linux, MacOS and Windows
Part 3: test project (PDF)
- Project step-by-step
- Oh, shit, git! Where to go if a problem occurs
- Guide to Forking a repo
- Use and properly format Git commit messages
- Github's issue tracker
- Beginner's Guide to Documentation
- Documentation in Python
- Style guide for Python Code (PEP 8)
- Python Docstring Convention (PEP 257)
- Packaging your Python Project - setup your python scripts as a python package and upload it to PyPi
- Google's Open-Source Style Guide
Part 5: From a simple python file/notebook to a publishable python package (document)
Summary:
| Topic | Tools |
|---|---|
| Refactoring code to have 1) data downloadable through link (2) functions 3) tests for functions | Jupyter notebook, assert |
| How to setup a small Python library (though the example is in python, participants are encouraged to use their own research code in whichever language they prefer) | Python packaging guide |
| Use doc-strings for functions and modules | Python Docstring Convention (PEP 257), other resources from Part 4 |
| Overview of version control with git and setting up an online repository | resources from Parts 1-3 |
| Discussion on choosing an open-source license | Choose a license, OSI Licenses |
| Including a Code of Conduct and Contributing Guidelines | Contributor Covenant, Code of Conduct |
| How to write automated tests in Python | Pytest |
| Setup continuous integration services to check that the code is tested on every update | TravisCI |
| Write and publish documentation on ReadTheDocs, a free hosting service for open source software projects | ReadTheDocs |
Part 6: website with GitHub Pages (document)
- Basic markdown guides
- Guide to GitHub Pages with Markdown
- Mastering Markdown
- Practice on an online Markdown editor (https://dillinger.io/). Jupyter notebooks have markdown cells as well.
- Markdown quick reference cheat sheets: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet and https://en.support.wordpress.com/markdown-quick-reference/
- Primers on HTML and CSS styling.
- HTML: https://www.w3schools.com/html/html_basic.asp
- CSS: https://www.w3schools.com/html/html_css.asp
- A quick preview
| Tool | Description |
|---|---|
| GitHub Guides | A set of guides to GitHub (check also their videos) |
| GitHub for Atom | A GitHub plugin for the Atom text editor, in case you don't want to install a complete Git GUI client |
| Start Bootstrap | A library of free open-source website themes and templates that you can download or directly view on GitHub |
| Zenodo, Figshare | For sharing large data files used in your research; version control; DOIs for data |
| CorTex | A living paper! The paper lives in a GitHub repository. Figures are generated by python scripts and maintained up to date by Travis-CI |
| Git Lfs | Version control for large data files |
Screencast of workshop on Youtube
Have other resources to suggest? Feel free to add an issue to this repository! :)