Skip to contents

Contributing to reiod

Source: .github/CONTRIBUTING.md

Thank you for taking the time to contribute. This file explains how to report a problem, how to propose a change, and the one rule that is specific to this package: the cut-off values are not ours to change.

Code of conduct

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

Reporting a problem

Open an issue at https://github.com/nicholustintzaw/reiod/issues. The most useful reports include:

  • a minimal reproducible example, ideally with reprex. The shipped eiod_demo data is a good starting point, and avoids sharing your own survey data;
  • the output of sessionInfo();
  • what you expected to happen, and what happened instead.

Do not attach survey microdata or anything that could identify a respondent or household. If a problem only shows with your data, reproduce it on eiod_demo or on a few made-up values.

If the issue is about a result (a classification you believe is wrong), please include the indicator, the demographic group, the value, and the cut-off it was compared with, from eiod_lookup_cutoff(). Most such reports turn out to be a unit mismatch; eiod_check_data() usually finds it.

Proposing a change

Small fixes (typos, documentation wording) can go straight to a pull request. For anything larger, please open an issue first, so we can agree on the approach before you spend time on it.

  1. Fork the repository and create a branch from main.
  2. Make your change. Edit the roxygen comments in R/, never the files in man/ or NAMESPACE, which are generated by devtools::document(). Edit README.Rmd, not README.md, then re-knit it with devtools::build_readme().
  3. Add or update tests in tests/testthat/ for any change in behaviour.
  4. Run devtools::test() and devtools::check(). Both should pass with no errors or warnings.
  5. Add a bullet to the top section of NEWS.md describing the change from a user’s point of view.
  6. Open a pull request against main, explaining what changed and why.

tools/build.R lists the full rebuild sequence.

Style

  • Function and argument names are snake_case. Every exported object starts with eiod_.
  • The package has no dependencies beyond base R (stats and utils). Please do not add a package to Imports without discussing it in an issue first; packages used only in tests or vignettes go in Suggests.
  • Functions take plain vectors (df$column), not unquoted column names.
  • Report problems with stop(), warning() or message(); use cat() only inside print() methods.

The cut-off values

The 616 cut-offs in data-raw/eiod_cutoffs.csv are transcribed from Intake’s methods paper, Methods for Assessing Healthy, Environmentally Sustainable Diets Globally (Tables 3 and 4a–4g). Eight Table 3 eutrophication values carry a correction supplied by Intake and are marked in the value_source column.

These values change only on Intake’s instruction: a revised paper, or a written correction from Intake. A pull request that edits a cut-off must cite that source. If you believe a value is wrong, please open an issue rather than a pull request, quoting the table, row and column, and what the paper prints.

When a value does change:

  • edit data-raw/eiod_cutoffs.csv only, then rebuild with source("data-raw/build_data.R"). The script stops if any value no longer round-trips to its published digits;
  • tests/testthat/test-reference_values.R compares cut-offs against values typed by hand from the paper, so it needs updating in the same pull request;
  • the same CSV is shared with the companion Stata package eiod, so a change there is needed too.

Acknowledgement

Contributors are credited in NEWS.md. People who make a substantial contribution to the code or documentation are added to Authors@R in DESCRIPTION, with their agreement.