How to raise an issue

Help us help you

Mauro Lepore https://github.com/maurolepore
2020-06-26

Open source packages improve thanks to people like you who kindly contribute to open source software. Your contribution to the packages we build can be as simple as raising an issue. Here is how you can do just that.

Each package has a website with a link to report a bug or raise any in-scope issue (more on this below). For example, the website of the package r2dii.match lives here and looks like this:

The website of every package has a link to report a bug.

Figure 1: The website of every package has a link to report a bug.

The link to report a bug opens a page that, like an email, has two parts:

  1. A title to summarize your issue;
  2. A body to detail your issue. We know you are busy; please follow our instructions carefully to avoid emails and solve the issue quickly.
The web page to report a bug is like an email.

Figure 2: The web page to report a bug is like an email.

What’s beyond our scope

Our scope is limited. We assume you are familiar with R. (To learn R see our favorite resources.) The issues we can address are those caused specifically by the packages we build. Report everything else at https://stackoverflow.com/ or https://community.rstudio.com/.

The most common out-of-scope problems are installation errors. It’s unlikely the problem comes from our packages because we continuously check that they install correctly – with multiple version of R, and on Windows, Linux, and several other platforms). What should you do then?

A tale of two R programmers

Mike and Lucy are working together and want to use the package r2dii.match. They try to install it with install.packages("r2dii.match") but they get an error.

Mike: “Bummer!”

Lucy: “Wait; let’s read the error message carefully.”

The error message makes no sense. Mike Googles it and finds some promising results. Lucy tries a few hacks but nothing works.

Lucy: “It’s all sooooooo confusing; but there is something about versions, right? These R geeks move fast – they pump new stuff every day!”

Mike: “What if we ask at RStudio community? They seem friendly.”

Lucy: “Yeah, those folks are cool. But let’s first update everything – I mean R, RStudio, and all R packages. It can’t hurt and sooner or later we’ll have to do it anyway. Here is a nice guide.”

Mike: “That’ll take a while but you are right. Let’s bite the bullet.”

After an hour or so.

Lucy: “Okay, done! Here we go again.”

Mike: “Fingers crossed.”

They look at each other. Then Lucy runs install.packages("r2dii.match"). Then it just works.

Bottom line: Get current people1.


  1. Get current, people. You don’t want to adopt new things on day one. But at some point, running old versions of software adds unnecessary difficulty. – How to think about upgrading R and RStudio↩︎

Citation

For attribution, please cite this work as

Lepore (2020, June 26). Data Science at 2DII: How to raise an issue. Retrieved from https://2degreesinvesting.github.io/posts/2020-06-26-instructions-to-raise-an-issue/

BibTeX citation

@misc{lepore2020how,
  author = {Lepore, Mauro},
  title = {Data Science at 2DII: How to raise an issue},
  url = {https://2degreesinvesting.github.io/posts/2020-06-26-instructions-to-raise-an-issue/},
  year = {2020}
}