Dependency Management

Introduction

Most tools have dependencies on other software packages. For example, if you write code in R you likely depend on both the version of the R language and other R packages, while if you write in C++ you may need to use specific compilers. Most software will be supported differently by different operating systems.

This guide aims to clarify how to declare and manage software dependencies, as well as how to deal with backwards compatibility.

Declaring/listing dependencies

A first and necessary step is to make it very clear to the user what dependencies your software needs to run. This sounds simple, but very few tools actually do this adequately. Different languages have different places for this (e.g., For R packages, it is standard to list the dependencies in the DESCRIPTION file). If there is no other guidance, one of the best places to declare dependencies is on your Github repository’s README page. You can simply create a “Dependencies” header in the README and list the dependencies out.

The DESCRIPTION file in R packages

In R, dependencies are listed within the package directory in a file named “DESCRIPTION” (note, there is no file extension). You should include which R version is needed to run your package under “Depends:”. There are two ways to include package dependencies - R packages that are required for your software to run should be declared under the “Imports:” section of your DESCRIPTION file, while packages that are helpful (i.e. to run examples or the user manual) can be listed under “Suggests:”. Ideally, you can also specify which version of each package your package depends upon in parentheses following the package name.

A best practice is to try to limit dependencies where possible some strategies include:

• If a package is only used in one or two “optional” functions, you can list it under “suggests.”
• Limit use of R packages that have a lot of dependencies themselves

More details are covered in the The R packages book.

Backwards compatibility

It is admirable to want to make software work with older software versions of dependent packages. However, to ensure backwards compatibility, the software should be explicitly tested with multiple versions. This can create headaches as the number of situations to test balloons quickly. For this reason, we think it is important to maintain backwards compatibility only when previous versions of software have a legitimate reason for use and continue to be used by a large variety of users. If it is expected that users continue to move forward (for example, updating their R version), there is no need to support backwards compatibility.

If backward compatibility is maintained, we recommend using GitHub Releases or tags to release older, backwards compatible software. This way, newer software can continue to be released while a stable build that supports older software versions is maintained. More information is available in the GitHub best practices post.