This contributing guide has been derived from the tidyverse boilerplate. Where it seems over the top, common sense is appreciated, and every contribution is appreciated.

Non-technical contributions to ruODK

Feel free to report issues:

  • Bug reports are for unplanned malfunctions.
  • Feature requests are for ideas and new features.
  • Account requests are for getting access to the ODK Central instances run by DBCA (DBCA business only) or the public demo server (contributors, to run tests).

Technical contributions to ruODK

If you would like to contribute to the code base, follow the process below.

This explains how to propose a change to ruODK via a pull request using Git and GitHub.

For more general info about contributing to ruODK, see the Resources at the end of this document.

Prerequisites

To test the package and build the vignettes, you will need valid credentials for the test server, currently the ODK Central Sandbox. Create an accont request issue to request access to those two ODK Central instances.

Before you do a pull request, you should always file an issue and make sure the maintainers agree that it’s a problem, and is happy with your basic proposal for fixing it. If you’ve found a bug, first create a minimal reprex.

PR process

Fork, clone, branch

The first thing you’ll need to do is to fork the ruODK GitHub repo, and then clone it locally. We recommend that you create a branch for each PR.

Check

Before changing anything, make sure the package still passes R CMD check locally for you. When in doubt, compare your R CMD check results with current results for ruODK on Travis (checks on Linux and/or MacOS) and, if applicable, AppVeyor (checks on Windows). You’ll do this again before you finalize your pull request, but this baseline will make it easier to pinpoint any problems introduced by your changes.

devtools::check()

Style

Match the existing code style. This means you should follow the tidyverse style guide. Use the styler package to apply the style guide automatically.

Be careful to only make style changes to the code you are contributing. If you find that there is a lot of code that doesn’t meet the style guide, it would be better to file an issue or a separate PR to fix that first.

styler::style_pkg()

Document

We use roxygen2, specifically with the Markdown syntax, to create NAMESPACE and all .Rd files. All edits to documentation should be done in roxygen comments above the associated function or object. Then, run devtools::document() to rebuild the NAMESPACE and .Rd files.

See the RoxygenNote in DESCRIPTION for the version of roxygen2 being used.

spelling::spell_check_package()
spelling::update_wordlist()
devtools::document(roclets = c("rd", "collate", "namespace"))

Test

We use testthat. Contributions with test cases are easier to accept. If you are not sure what parts of your code are covered by tests, run the following to get a local coverage report of the package so you can see exactly what lines are not covered in the project.

To run tests and build the vignettes, you’ll need access to the ODK Central sandbox instance. If you haven’t got an account yet, create an accont request issue to request access to those two ODK Central instances.

You will need to use the following environment variables:

ruODK::ru_setup(
  test_url = "https://sandbox.central.getodk.org",
  test_pid = 14,
  test_fid = "build_Flora-Quadrat-0-4_1564384341",
  test_un = "[email protected]",
  test_pw = "...",
  tz = "Australia/Perth" # or any valid timezone
)

Keep these settings outside of version control, e.g. in your ~/.Renviron. Note: ~/.Renviron contains simple key=value assignments without Sys.setenv().

# Required for testing
ODKC_TEST_URL="https://sandbox.central.getodk.org"
ODKC_TEST_PID=14
ODKC_TEST_FID="build_Flora-Quadrat-0-4_1564384341"
ODKC_TEST_FID_ZIP="build_Spotlighting-0-6_1558333698"
ODKC_TEST_FID_ATT="build_Flora-Quadrat-0-1_1558330379"
ODKC_TEST_FID_GAP="build_Turtle-Track-or-Nest-1-0_1569907666"
ODKC_TEST_FID_WKT="build_Locations_1589344221"
ODKC_TEST_UN="[email protected]"
ODKC_TEST_PW="..."
RU_TIMEZOME="Australia/Perth"

# Useful for day to day use - use your own settings
ODKC_URL="https://odkcentral.dbca.wa.gov.au"
ODKC_PID=1
ODKC_FID="build_Predator-or-Disturbance-1-1_1559789410"
ODKC_UN="[email protected]"
ODKC_PW="..."

Keep in mind that ruODK defaults to use ODKC_{URL,UN,PW}, so for everyday use outside of contributing, you will want to use your own ODKC_{URL,UN,PW} account credentials.

devtools::test()
devtools::test_coverage()

NEWS

For user-facing changes, add a bullet to NEWS.md that concisely describes the change. Small tweaks to the documentation do not need a bullet. The format should include your GitHub username, and links to relevant issue(s)/PR(s), as seen below.

Re-check

Before submitting your changes, make sure that the package either still passes R CMD check, or that the warnings and/or notes have not changed as a result of your edits.

devtools::check()
goodpractice::goodpractice(quiet = FALSE)

Commit

When you’ve made your changes, write a clear commit message describing what you’ve done. If you’ve fixed or closed an issue, make sure to include keywords (e.g. fixes #101) at the end of your commit message (not in its title) to automatically close the issue when the PR is merged.

Push and pull

Once you’ve pushed your commit(s) to a branch in your fork, you’re ready to make the pull request. Pull requests should have descriptive titles to remind reviewers/maintainers what the PR is about. You can easily view what exact changes you are proposing using either the Git diff view in RStudio, or the branch comparison view you’ll be taken to when you go to create a new PR. If the PR is related to an issue, provide the issue number and slug in the description using auto-linking syntax (e.g. #15).

Review, revise, repeat

The latency period between submitting your PR and its review may vary. When a maintainer does review your contribution, be sure to use the same conventions described here with any revision commits.

Resources

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Maintaining ruODK

The steps to prepare a new ruODK release are in data-raw/make_release.R. It is not necessary to run them as a contributor, but immensely convenient for the maintainer to have them there in one place.