R Package Development Quickstart Guide

This Quickstart Guide lays out the general steps you should follow to develop and publish an R package that conforms with the IQSS Best Practices for R Statistical Software Development.

The IQSSdevtools R package automates much of the work of setting up the package, checking that it can be built/passes its tests, and publishing it. To install IQSSdevtools type the following into your R console:

library(devtools)
install_github("hadley/pkgdown")
install_github("IQSS/IQSSdevtools")

While IQSSdevtools automates much of the process of implementing the best practices, you will of course still have to manually fill in the package's contents--source code, documentation and many of its tests. For extended details on how to do this, in this Quickstart Guide we link to other resources, including relevant sections from Hadley Wickham's (HW) free book R Packages.

We also highly recommend using RStudio for package development. This program has many built in capabilities that make package development easier.

1. Initializing the package

Before starting up R, we recommend getting a GitHub account here, if you don't already have one. You can use GitHub to remotely store your (version controlled) code in a GitHub "repository". The service also enables collaboration and provides a platform for your users to report bugs. For more details about Git and GitHub see HW: Git and GitHub.

Once you have a GitHub account, you should get a GitHub personal access token. To do this visit the GitHub tokens website. Having a personal access token will allow IQSSdevtools to create your package's GitHub repository, as well as update it as you make changes to your package.

After getting your GitHub personal access token, open R and use IQSSdevtools to initialise your new R package. For example, imagine we want to start a package called MyPackage in our current working directory and our GitHub personal access token is adfaoihgalkxygoidsn. Initialize this package using the following code in the R console:

IQSSdevtools::init_iqss_package(path = "MyPackage",
                                github_auth_token = "adfaoihgalkxygoidsn")

Running this function will create a new folder called MyPackage in your current working directory. This folder will contain a "skeleton" R package that includes all of the basic files you will need to meet the IQSS best practives. You should only call this function once. Also, do not store your GitHub personal access token in publicly accessible files, such as a file in your GitHub repository. It should be kept secret.

Now that your package is initialized, you need to manually fill in the package's contents. On your desktop, navigate to the new MyPackage folder. Using a text editor or RStudio, add contents to the following files/folders:

  • The README.Rmd file: This file will likely be your users' introduction to the package. As such it should include a brief description of the package's purpose, syntax, and a quickstart guide. For a quick introduction to writing a README.Rmd see the IQSS R Markdown Introduction. Also, for complete README example, see the Zelig README. {BADGES: I want to write a package that will automatically add in the appropriate badges, so that users don't need to think about this}

  • The DESCRIPTION file: This contains the package's metadata, e.g. authors' names, a description of what the package does, other packages required by your package, and so on. For details see HW: Package metadata. init_iqss_package will include in the DESCRIPTION a link to the package's GitHub main page {CHANGE TO OPEN SCHOLAR WHEN AVAILABLE} and Issues page. The latter is a platform for users to contribute to the package's development and report bugs.

  • The NEWS.md file: A file where where you record all of the major and minor changes that you have made the package for each version. For an example see Zelig NEWS.md.

  • The R folder: This folder contains all of your package's R source code. You will also use the R source code files you create in this folder to document your package's objects--e.g. functions and data sets. For details on how to organize your R code see HW: R code. For a quick start guide on how to write function documentation see the IQSS Roxygen Introduction.

Advanced, but important to do before publishing your package

  • The vignettes folder: Vignettes are longer-form documentation, generally used for detailed descriptions of methods and package syntax. They often take the form of articles or book chapters. For more details see HQ: Vignettes.

  • The tests folder: This folder contains all of the tests you will use to ensure that your package does what you want it to. For details on how to write R tests see HW: Testing. The init_iqss_package function also sets up the basic infrastructure for you to run your tests on Travis CI and Appveyor servers. These services allow you to test that your package is able to build and passes its tests in environments other than locally on your computer. Travis CI runs the tests on a Linux (and optionally macOS) system. Appveyor tests it on Windows. For details on how to set up these tools and implement them in a "test-driven" workflow see the IQSS R testing webpage {INCOMPLETE}.

  • {FILL IN WITH COMMUNITY BUILDING PLATFORMS GOOGLE GROUPS ETC}

2. Build, test, and version control your package

As you fill in the contents of your package's files, you should regularly build, test, and version control it. Building the package ensures that all of the code is valid (e.g. that all opening brackets [ are closed ]) and compiles the documentation. Testing the package ensures that all of the tests you have created in the tests folder pass as expected. It also checks that your package meets the Comprehensive R Archive Network (CRAN) requirements. For more details on building and testing packages see HW: Checking.

After your package has been built and tested, you want to "commit" the changes you have made to git version control. Finally, you want to "push" these commits to your package's GitHub repository so that they are saved remotely and others can access the files and collaborate on their development.

All of these steps--build, test, commit, and push--can be completed with one call of the build_iqss_package function from the IQSSdevtools package, e.g.:

IQSSdevtools::build_iqss_package(
        commit_message = "A brief description of changes since last commit")

Note in this and the following example, the package is assumed to be the working directory.

The build_iqss_package function also documents your package's minimal compliance with the IQSS Best Practices by generating a Report Card. The Report Card is stored in a file within your package called .iqss_reportcard.yml.

3. Releasing your package

When your package's source code and documentation are written, the package can be built, and passes all tests, you should publish it. To do this, use IQSSdevtools' publish_package function {INCOMPLETE}.

publish_package(commit_message = "A brief description of the release")

This function call does the following operations:

  • Runs build_iqss_package to make sure the package can be built and passes all tests, updates the IQSS report card, and pushes the code to GitHub.

  • Adds a git tag with the current package version number. The git tag makes it easier for contributors to access specific past versions of the package source code on GitHub.

  • Submits the package to CRAN so that it can be easily installed by users with a call to install.packages("My Package").

  • {ADD IN SOFTWARE CITATION DETAILS}

A note on version numbering

Package version numbers are stored in your DESCRIPTION file under the Version field. Each package release should have an informative version number indicating what kind of release it is. Use a version numbering convention called semantic versioning to indicate to your users how significant a given release is (and so how it might affect their code).

A package version number that follows semantic versioning consists of three numbers separated by periods, e.g. 1.2.3. The numbers indicate MAJOR.MINOR.PATCH changes. MAJOR changes are changes that fundamentally change the package's code such that the release is not completely compatible with previous versions. MINOR changes add functionality to a package while being backwards-compatible. PATCH changes introduce backwards-compatible bug fixes.

For example, if your current version number is 1.2.3 and you introduce a backwards-compatible bug fix, before you run publish_package you should change the Version field in your DESCRIPTION file to Version: 1.2.4.

results matching ""

    No results matching ""