Skip to contents

Contributing

Source: vignettes/contributing.Rmd
contributing.Rmd

General guidelines

This article outlines how to propose a change to sixtyfour. For more information about contributing to this, and other WILDS projects, please see the WILDS Contributing Guide.

Fixing typos/docs changes

You can fix typos, spelling mistakes, or grammatical errors in the documentation directly using the GitHub web interface, as long as the changes are made in the source file.

Bigger changes

If you want to make a bigger change, it’s a good idea to first file an issue and make sure someone from the team agrees that it’s needed.

If you’ve found a bug, please file an issue that illustrates the bug with a minimal reproducible example using reprex.

Pull request process

  • Fork the package and clone onto your computer
  • Create a Git branch for your pull request (PR)
  • Make your changes, commit to git, and then create a pull request.
    • The title of your PR should briefly describe the change.
    • The body of your PR should contain Fixes #issue-number.
  • For user-facing changes, add a bullet to the NEWS.md file.

Code style

Testing

We strive to have all tests that do HTTP requests do so against resources that are not actual AWS accounts given the drawbacks with using real accounts, e.g., setting them up can be difficult at some organizations; forgotten resources can be expensive; accidentally making unwated changes to an account, etc.

We use two tools to replace real AWS accounts: Minio, Localstack.

Minio

We use Minio for testing functions in this package (functions that start with aws_bucket and aws_file) for interacting with S3.

Local

If you want to run tests while contributing to sixtyfour, the tests that use Minio will just be skipped if you don’t have Minio running.

To use Minio, first install it for your platform: MacOS, Windows, Linux.

Next, start Minio. Within this package is a make target minio_start for starting Minio locally. That make target should only work on Linux and MacOS platforms. To start Minio on the command line see the docs links above for each platform.

Upon starting Minio it will display URLs for both the Minio API and WebUI - and your username/password to login to the WebUI. You can open up the WebUI as a nice visual dashboard of what’s going on.

GitHub Actions

The R-CMD-check workflow in .github/workflows/ includes spinning up Minio for running unit tests - but only on Linux; tests that require Minio are skipped on MacOS and WIndows platforms on GitHub Actions.

Minio Details

The following (collapsed) bullets list information for those who want to know more about the minio setup, and that may want to tweak it or add minio setup to other tests.

Expand for details
  • tests/testthat/helper-minio.R has helper functions for Minio. bucket_delete and buckets_empty make it easier to do cleanup in tests. The minio_available function is to be used inside skip_if_not to skip the tests in the file if Minio is not available, like: skip_if_not(minio_available(), "Minio Not Available")
  • At the top of any file that uses Minio, setup the interfaces to Minio like:
Sys.setenv(AWS_PROFILE = "minio")
buckets_empty() # empty buckets so we're starting from an empty slate
  • And unset at the bottom of the file to cleanup:
buckets_empty() # empty buckets
Sys.unsetenv("AWS_PROFILE")

Internally we grab client objects for paws and s3fs as needed and use AWS_PROFILE env var to toggle on/off using Minio.

Localstack

We use Localstack for testing some functions in this package.

Local

If you want to run tests while contributing to sixtyfour, the tests that use Localstack will just be skipped if you don’t have Minio running.

To use Localstack, first install it for your platform https://docs.localstack.cloud/getting-started/installation/.

Next, start Localstack. Within this package is a make target localstack_start for starting Localstack locally. That make target should only work on Linux and MacOS platforms. To start Localstack on the command line see the docs links above for each platform. You’ll need Docker installed and running to run Localstack. There are probably non-Docker ways to run Localstack.

For a GUI interface to the locally running localstack you can install the Desktop client - which isn’t very good - at https://docs.localstack.cloud/getting-started/installation/#localstack-desktop. Better yet, login to the cloud Localstack site and you can interface with your locally running Localstack in the better interface there. Login at https://app.localstack.cloud/.

GitHub Actions

The R-CMD-check workflow in .github/workflows/ includes spinning up Localstack for running unit tests - but only on Linux; tests that require Localstack are skipped on MacOS and WIndows platforms on GitHub Actions.

Localstack Details

The following (collapsed) bullets list information for those who want to know more about the Localstack setup, and that may want to tweak it or add Localstack setup to other tests.

Expand for details
  • tests/testthat/helper-localstack.R has helper functions for Localstack. The localstack_available function is to be used inside skip_if_not to skip the tests in the file if Localstack is not available, like: skip_if_not(localstack_available(), "Localstack Not Available")
  • At the top of any file that uses Localstack, setup the interfaces to Localstack like:
Sys.setenv(AWS_PROFILE = "localstack")
  • And unset at the bottom of the file to cleanup:
Sys.unsetenv("AWS_PROFILE")

Internally we grab client objects for paws and s3fs as needed and use AWS_PROFILE env var to toggle on/off using Localstack.

Code of Conduct

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