Skip to content

Material for the AGU2018 workshop "Best practices for modern open-source research codes"


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



25 Commits

Repository files navigation

Best practices for modern open-source research codes

Material for the workshop at the AGU 2018 Fall Meeting.

Conveners: Leonardo Uieda, Lindsey Heagy, Lion Krischer, Florian M. Wagner

Location Grand Hyatt / Room: Penn Quarter
Time Wednesday, 12 December 2018 / 13:40 - 18:00
Workshop ID WS24
Shared notes Google Docs


Modern science increasingly relies on code, ranging from small scripts to workflows with many interacting parts. Reproducibility and extension of studies employing these codes require that they are accessible. The open-source community has established modern best-practices for making software available, usable, and maintainable. In this workshop, we will demonstrate a workflow for publishing research code following these best-practices. We will cover open-source licenses, version control, automated testing, documentation, and continuous integration. The workshop will be hands-on: participants will work to set up a project using sample code provided by the instructors. By the end, participants will have the knowledge needed to continue learning independently and apply these practices to their own research code. These resources can be applied to any programming language or scientific discipline.

Learning Objectives

Our aim with this workshop is for participants to:

  1. Gain awareness of tools available to researchers within the open-source ecosystem including Jupyter, git, ReadTheDocs, continuous integration services (for testing), etc
  2. Learn modern best-practices for structuring a repository for research software that promotes accessibility, reusability, and reproducibility
  3. Learn about the tools available for testing, publishing documentation, and versioning that can be immediately applied to their own codes

Tentative Agenda

During the workshop, we'll introduce these topics by working through an example. The goal is to convert a notebook (or script) that does some data analysis into a Python library that is tested, documented, and can be reused. The final version of the library and a history of each step in the conversion process can be found at

Duration (min) Topic Tools
15 Introduce the motivations and problems that the workshop will address Example data analysis in Jupyter
30 Describe the example we will working through and provide an overview of the Jupyter notebook Jupyter notebook
45 Overview of version control with git and setting up an online repository GitHub, Slides
45 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
15 Discussion on choosing an open-source license Choose a license, OSI Licenses
15 Including a Code of Conduct and Contributing Guidelines Contributor Covenant
30 How to write automated tests in Python Pytest
30 Setup continuous integration services to check that the code is tested on every update TravisCI
30 Write and publish documentation on ReadTheDocs, a free hosting service for open source software projects ReadTheDocs
15 Overview of other resources available within the open source community

Before the workshop

If you would like to follow along interactively during the course, please do the following before the course starts:

  • Download and install Anaconda. Use the latest version of Python 3 and be sure to check the box that says "Add Anaconda to my PATH environment variable" if on Windows.


After the workshop

Since the time allocated for the workshop does not allow to cover scientific software development in its entirety, we provide links to some alternatives and guides to extend and deepen some of the taught concepts.

Further reading

Alternatives to the tools presented

  • Version control

    • GitLab: Version control for with private repositories and for your own server
  • Continous Integration

  • Documentation

    • MkDocs: Fast and simple project documentation using Markdown.



Workshop - AGU 2018


Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License.


Material for the AGU2018 workshop "Best practices for modern open-source research codes"







No releases published