19 How to contribute

You can play a very important role in improving the projects from the group. While we write software with the hope that others will use it, we are the first users and thus any questions we have are very likely to be questions external users will have. The earlier we fix these issues the better as more people will benefit from the improvements. Overall, there are many ways in you can help. Below is a list of some areas you might be interested in contributing to.

19.1 GitHub Issues

Given that we use GitHub for most of our projects, one of the most direct ways to start contributing is by raising issues. There are many things we can do with issues as highlighted by this guide. However, their main use is to help us improve our own code and documentation. For example, maybe the help file for a function in one of our packages has a typo, is not clear, or assumes a lot of background knowledge. Letting the team know that that’s the case is the first step.

Let’s say that we want to write an issue about the jaffelab::expression_cutoff() function. The following steps show you what I would do.

Go to the GitHub repository for jaffelab which is https://github.com/LieberInstitute/jaffelab.
Then I would find the latest commit from https://github.com/LieberInstitute/jaffelab/commits/master, which right now is https://github.com/LieberInstitute/jaffelab/commit/6a1c61bb3748aeb73890c1ab2aa59e5cc20bc08b.
Then I would click on “browse files” which takes me to https://github.com/LieberInstitute/jaffelab/tree/6a1c61bb3748aeb73890c1ab2aa59e5cc20bc08b. 1. There, you can navigate to the file of interest, in this case, https://github.com/LieberInstitute/jaffelab/blob/6a1c61bb3748aeb73890c1ab2aa59e5cc20bc08b/R/expression_cutoff.R.
Next you can highlight the relevant lines. In this case, we think that the definition of the expr argument can be improved. So that corresponds to https://github.com/LieberInstitute/jaffelab/blob/6a1c61bb3748aeb73890c1ab2aa59e5cc20bc08b/R/expression_cutoff.R#L13-L14.
Next we can go to the issues page at https://github.com/LieberInstitute/jaffelab/issues and click on “New issue” and write the description of the problem we found while linking to the exact lines of code we think need to change. GitHub will then automatically show the code in the final issue and our issue will be protected in the sense that if the code at R/expression_cutoff.R changes and the lines we wanted to link to move around, our link will not be affected since we are linking to a specific past version of the code. Here’s the result https://github.com/LieberInstitute/jaffelab/issues/7.
Once an issue has been raised, others or even yourself might want to address the request and make the necessary changes to resolve the issue. The above issue was resolved by this commit.

A well documented issue makes everyone’s job easier and will help us improve our code and documentation.

19.2 Team websites

You are definitely welcome to contribute to the several team websites such as this one. Here’s a non-comprehensive list of these repositories:

The above repositories are configured to update automatically using GitHub Actions and bookdown.

19.2.1 LIBD rstats club website

One of the main contributions you might be interested in contributing is blog posts. This involves two repositories as described in this blog post. Since that blog post was written a few things have changed, although the overall idea remains. That is, we have two repositories:

I basically control the second one and your contributions should be at https://github.com/LieberInstitute/rstatsclubsource, which is how we setup things to keep blog post authors anonymous. You’ll likely contribute an Rmd and an html file inside the content/post directory. You might also want to add information about yourself at content/authors.

I recommend reading the blog post on how to contribute to this website and then meet with one of the recent blog post authors for a Data Science guidance session.

19.3 GitHub Actions

GitHub Actions are quite powerful and we are increasingly using them in several of our projects. The basic idea is that they enable us to use free computers for up to 6 hours to run some code whenever we make a GitHub push. So they are ideal for running code in standarized environments that would otherwise take us time to run in our local computers. For example, automatic R package checks or rendering the HTML files for a website.

19.3.1 R packages

biocthis is the R/Bioconductor package I developed for using GitHub Actions to test R packages in a Bioconductor-friendly way. In 2020-09-10 I presented biocthis to the Ryten lab and you can see the video and recording below. Ultimately, you’ll likely be interested in checking the documentation at https://lcolladotor.github.io/biocthis/ which includes a vignette describing the whole process for making this package. The main functions you’ll be interested in are biocthis::use_bioc_pkg_templates() as well as biocthis::use_bioc_github_action().

19.3.2 Websites

For rendering websites, I’ve edited the biocthis GitHub action workflow to render websites using bookdown or regular R markdown. Some additional repositories beyond the ones listed earlier that implement these workflows are:

https://github.com/LieberInstitute/SPEAQeasy (bookdown)
https://github.com/LieberInstitute/SPEAQeasy-example (bookdown)
https://github.com/LieberInstitute/VisiumLIBD (bookdown) https://github.com/LieberInstitute/recount3-docs (bookdown and postcards)
https://github.com/lcolladotor/twitter-stats (rmarkdown)

19.4 LIBD R/Bioconductor packages

As a group we have many R/Bioconductor packages. I’ve created a list of the ones I’m involved in at lcolladotor.github.io/pkgs/ which might have errors or open issues that need to be addressed. If you want to help with any of them or with other LIBD R/Bioconductor R packages, the most direct way to get involved is to open a new issue to start communicating with the maintainer(s) of the package.

For external R/Bioconductor packages, at some point in the LIBD rstats club we’ll have a session on how to make a pull request (TODO).