This is guide for “developers”, or anyone who is looking to contribute code to the wpa R package.
Please also read our CONTRIBUTING document on details regarding our Contributor License Agreement (CLA).
You should have the following installed before starting:
You should also have the following packages installed. These should all be available from CRAN: 1. devtools 2. tidyverse 3. roxygen2
Once these are all installed, you should be ready to get started.
Please try to adhere to the following package design principles before proceeding with code contribution.
To get started, you will need to fork and clone the wpa repository on your local machine. You will need to have either git or GitHub Desktop set up on your local machine (see Pre-requisites).
Here are the steps if you do not have repository access to
microsoft/wpa (if you have been granted direct access, you can clone directly):
When creating a fork on GitHub, you may be asked whether you are looking to contribute to the parent project or for your own purposes (see screenshot). Please select contribute to the parent project.
Codebutton on the repository page, and click ‘Open with GitHub Desktop’.
You may prefer to use git because it is more flexible, or because you have repository access and you are trying to directly clone the package from
microsoft/wpa and are failing to do so with GitHub Desktop. There is a known issue with GitHub Desktop that it could fail with 2FA authentication, in which case you can use git to authenticate properly.
Here are the steps:
wparepository, and copy the path to the folder. It is highly recommended that you create a new folder and name it
wpa. An example of this path would be
cd, and followed (separated with a space) by the path to the local folder above. You will need to add quotes, so the full command would look something like
cd "C:/My Documents/GitHub/wpa". See How to change folder with git bash? - Stack Overflow if you have issues changing directories.
wparepository, run the command
git init. This command initializes your folder as a git repository. In other words, it sets it up to do version control.
git remote add origin https://github.com/microsoft/wpa.git. This will “connect” your local folder with the Git repository. You may get some prompts for authentication somewhere around here. Run
git remote -vto check whether this has been successfully applied.
If you are in the situation where you are simply trying to overcome the authentication issue with GitHub Desktop, please read this paragraph. Once the authentication through Git Bash is set up, you may now go back to the GitHub Desktop GUI window. Go to
File > Add local repository and choose the
wpa folder that you have just set up. You may be asked to login again, but this should now allow you to fetch or pull from the repository. You are now set up!
After creating a copy of the repository on your local machine and having installed the repository version, you can start working with R.
PersonIdexists, and returns FALSE if it does not).
setwd()to change you working directory. Run
getwd()to check what your current working directory is.
collaboration_dist()would be saved in a file called collaboration_dist.R.
devtools::load_all(). This will simulate loading the package with the function in it. Run the function with some example data to ensure that it works.
roxygen2::roxygenise()), check the package (
devtools::check()), and install the package (
There are certain tricks which are helpful to know with developing or changing an R function, such as how to test the function and how to generate R documentation. This section will provide more information.
Once you’ve made changes to a script, here is how to update the package and install it locally on your computer. Run:
roxygenise() generates documentation files for the R package, and makes them available to the user.
Next, run this to build and check the package. You will need devtools installed.
This step runs a R CMD check against the package, to check that there will be no errors and issues if somebody installs the package. This step can take around 5 minutes long, and usually it is worth running this only after you’ve implemented all the desired changes towards the end.
If everything runs smoothly, run this final line to install the local package. Make sure that your working directory is set to the package!
devtools::install() would install the package directly from the directory in your local machine, i.e. the version that you are developing. If you would like to install the stable GitHub version from the
main branch, you will need to run:
devtools::install_git(url = "https://github.com/microsoft/wpa.git")
If you’d like to install from a particular branch or install vignettes, you can leverage the additional arguments available with
devtools::install_git(), for example:
devtools::install_git(url = "https://github.com/microsoft/wpa.git", branch = "feature/network-functions", build_vignettes = TRUE)
Once you are sure that everything works, you can push your changes to GitHub either with git or GitHub Desktop. Depending on the set-up, the method to merge is different:
microsoft/wpa(assuming you have access), you are recommended to either create a new branch or push the changes to an existing patch branch that is not the main repository. It is recommended that you never push changes directly to the
mainbranch so that you do not introduce any breaking changes.
For commit messages, we would ask you to add an intuitive commit message so others will know what you have changed to the code. Please see the wiki page of this repo for a style guide on the commit messages.
The next step is to create a pull request to merge your changes to
microsoft/wpa. The repository itself provides a pull request template on what information you should include in the pull request. A maintainer will reply and review your pull request once it has been successfully submitted.
Each package release has a corresponding package version (e.g. 1.4.2.) To change that package version number for a particular release, simply go into the
DESCRIPTION at the project root folder of the wpa package. You can edit this with any notepad software or RStudio.
Change the values that come after
Version: to change the package version. Prior to incrementing the package version, please align with the main developer team on the agreed version release details.
Our current protocol for package release is to distribute it as a zipped file or a tar ball. The advantage of this approach is that users do not need to have a GitHub account, and this package release can be distributed via SharePoint or even email. Our current approach is to offer both options for installation.
Once you are happy with the package and all checks have passed, you can run the following to generate a zipped distribution of the package. If your platform is Windows, this should generate a zipped file one level above your project directory:
devtools::build(binary = TRUE)
The code to generate a tarball distribution is similar:
devtools::build(binary = FALSE)
After the zipped file and the tarball files have been generated, they are ready for distribution.
It is good practice to distribute a package with an updated version of the documentation, so users won’t be using outdated documentation. You can generate the familiar PDF documentation by running the following:
We recommend Karl Broman’s guide on Writing documentation with Roxygen2.