GitHub and the working group

Over the past year, I’ve been co-organizing a jointly-funded, large, international working group (with co-PIs Maria Dornelas, Mary O’Connor, and Andrew Gonzalez). The group has had several meetings now (October 2014, May 2015, June 2015) and will meet again next week with the goal of finishing ongoing projects and making major progress on several new ones. I’ve learned a lot about managing large collaborative working groups through this process, but one area I’ve been thinking a lot about this week is how to maintain good communication before, during, and after the working group, especially with respect to code.

Since our group is particularly large (> 25 participants) and since different combinations of participants have attended different meetings, communicating the important discussions, decisions about data and analysis, progress on projects, and general bwg-montrealworking group goals has been a challenge, and somewhat of a moving target. Overall, I think we’ve managed this generally well, by having semi-regular discussions among the co-PIs, having subsets of participants help on “core teams” to work on specific data, models, or manuscripts between working group meetings, and by using online collaborative tools such as Google Docs for writing manuscripts and keeping track of meeting notes.

As we prepare for a meeting that will be more strongly focused on using models and data analysis to test hypotheses, it is critical to also keep track of the code we are developing, and to ensure that members within our group (as well as future collaborators, reviewers, and manuscript readers) can understand what we did. In my own work, I rely on git and GitHub (www.github.com) to help me remember what I’ve been working on, be able to quickly resolve mistakes, and to share my code with collaborators or as Supplementary Material to a manuscript.

I’ve proposed that our working group use GitHub as the main place to keep track of and share code being developed for the projects. On GitHub, it is possible to request a private Organization for educational or research purposes, which allows the code to be developed privately within the group (e.g., only invited collaborators can view the Organization’s repositories), but later released publicly when the final product is ready. An Organization allows large teams (potentially with varying read/write permissions) to view, develop, edit, and comment on repositories from a central location – a great tool for a working group! I am aware that members of our group have varying levels of comfort with this tool (no familiarity, have an inactive account, regularly use, complex collaborative workflow), but my goal is for us to have a central “master” location for developing code (versus people’s personal repositories, laptops, or email), and a place to discuss issues that arise – rather than a barrier for participants who are not currently using or familiar with GitHub, or uncomfortable with developing code “out in the open”.

With this in mind, it seems like for a large working group, it would be useful to develop a set of guidelines for our GitHub Organization, that include how to set up and use repositories, communication, preferred style formats, and links to cheatsheets or guidelines for novice users, as well as a README.md template that could be used for each new project repository. Researchers are generally very busy, and the guidelines should be concise and informative so they don’t end up TL;DR.

I’m curious if others have used GitHub for large working groups, if you developed a set of use guidelines, and how you felt the approach was received (Were participants on-board with the plan? Did it help your code organization?). If you developed a set of basic guidelines, what main points did you emphasize the most? What are the major basic points to get across to GitHub novice-advanced users? Is there anything you see in the proposed guidelines below that seems unclear, too wordy, or incorrect? I’d love to hear what has worked (0r not) for other teams.

Here’s what I’ve outlined so far:

OrganizationTools

Contains guidelines for collaborating in the GitHub Organization for the working group. In order to keep track of what we’ve done, enhance reproducibility, improve communication across groups, and to be able to easily track down and fix potential errors, we strongly encourage all sub-groups to use GitHub to store and edit code related to the main projects.

1. Each new Project or Paper should have its own repository

  • repositories should have short, but informative, names, with no spaces

2. What should each repository contain?

  • README.md file – this file has brief text with the names of the main participants, the main questions being addressed (like a mini-abstract), and the main tools (R, R packages, datasets) that are needed to run the code. It should also include any important information someone new looking at the project would need to run or understand the code (e.g. the code needs to be run on a server, dependencies, known bugs, or the order in which multiple files are to be run).
    • Please look at the README_template.md file in this repository as an example.
  • If you are unfamiliar with markdown, you can find a cheatsheet here.
  • code – we anticipate that most projects will be done using R scripts, but other code is OK, if it is useful/necessary. Ideally, the code will allow a user to go from raw data to final figures and results.
  • DO NOT PUT DATA FILES ON GITHUB – While small data files can often be stored on GitHub without causing large issues, larger datafiles or files that are frequently edited may exceed GitHub’s storage space and cause problems downstream. It would be better to access the data within the code from it’s home on Dropbox (or elsewhere), and be really clear in your README file about which data you are using.

3. At a minimum, someone from each break-out group should update the repository at the end of the day (but feel free to commit your changes more frequently!).

  • Please use short, but informative commit messages that clearly describe what the new changes accomplish. Ideally, each commit message represents a cohesive “chunk” or a single type of update (e.g. NOT “We made a lot of changes in 5 different files that all run models”).

4. Strive for clear communication among team members to keep track of changes, comments, and bugs in the code being developed.

  • Use short, informative commit messages (see above)
  • We don’t need to follow a really complex workflow (e.g. you can update files in the repositories directly instead of using pull requests), but we can use some of the tools to help us keep track of comments and issues
    • Issues are a way for code collaborators to comment and receive notification about a particular question, bug, or opinion about the code, and to be able to join a broader discussion. You can read more about issues here.
    • When submitting an issue, please try to briefly (1) clearly describe the problem and exactly where in the code it occurs, (2) explain why, specifically, it is a problem for you, and (3) try to reproduce the error, suggest what might be causing the problem (line of code, commit, or data) and/or suggest a possible solution (if you don’t have one yourself).

5. As much as possible, follow consistent code format and style guidelines so that it can be more easily read and shared among team members.

  • R Style guidelines can be found here
  • Use TODO and FIXME comments to identify specific areas in the code that need attention
  • Don’t worry too much about specific styles, but consistent naming practices, good use of white space, and informative comments can go a long way towards making collaborative coding better!

 

Advertisements

4 thoughts on “GitHub and the working group

    • Me neither! I’ve heard of other working groups that tried this, but since their Organization repositories are usually private, I don’t know much about how others have organized their working group GitHub or how they felt it worked out at the end. Public examples I found came mainly from groups where it’s clear that all the members already are using git at a pretty advanced level, which doesn’t represent a lot of the ecology working groups that I know of. I’m a member of several other organizations, but in those cases all members have already “bought on” to using GitHub as part of the main workflow and communication, and have prior knowledge in using GitHub as a collaborative the tool. So it’s a bit of an experiment, but one that I think has a lot of positive outcomes if we can make it easy for working group members to use it!

      Like

  1. Hi Sarah, Great post! At Mozilla Science Lab (https://mozillascience.org/) we’re creating learning materials to help people do open science together, and we’re holding a series of Working Open Workshops. These are two-day training and networking events for scientists and researchers– we ran our first one in Berlin earlier this month (http://bit.ly/moz_wow)! You might be interested in our step-by-step guide on a GitHub workflow for collaboration (http://mozillascience.github.io/working-open-workshop/github_for_collaboration/). There’s also an intro GitHub presentation linked from that main WOW page. We’ll continue to develop more materials for users just like you and your collaborators, so we’d love to hear more about your experience with the working group.

    Like

  2. Pingback: GitHub and the working group – Part II | Supplementary Materials

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s