Skip to contents

Contribution Guidelines

Source: CONTRIBUTING.md

Thank you for taking the time to contribute to joinspy!

This document provides guidelines for contributing to joinspy—its codebase and documentation. These guidelines are meant to guide you, not to restrict you. If in doubt, use your best judgment and feel free to propose improvements through an issue or pull request.

Table Of Contents

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code and maintain a respectful, inclusive environment.

Installation

Obtaining the source

Clone the joinspy repository:

git clone https://github.com/gcol33/joinspy.git
cd joinspy

Setting up your R environment

  1. Install required tools

    • R (≥ 4.1)
    • Git
    • An editor or IDE (RStudio, VS Code, etc.)

  2. Install development dependencies

    install.packages(c("devtools", "roxygen2", "testthat", "rmarkdown", "knitr", "pkgdown"))

  3. Load the development build

    devtools::load_all()

Installing from source

Build and install the package locally:

devtools::install()

Regenerate documentation with:

devtools::document()

Testing

joinspy uses testthat for testing. All tests are located in tests/testthat/.

Run the full test suite:

devtools::test()

Run a complete package check:

devtools::check()

Guidelines: - Keep tests fast and reproducible. - Use set.seed() for random data. - Include edge cases and expected failures. - Prefer small examples to large datasets. - Test with base R, tibbles, and data.tables.

Documentation

Building the documentation

Build vignettes:

devtools::build_vignettes()

Build the pkgdown site locally:

pkgdown::build_site()

The generated site is saved in the docs/ directory.

Design of the docs

  • Function documentation: man/ (generated by roxygen2)
  • Tutorials and examples: vignettes/
  • Website configuration: _pkgdown.yml
  • Package overview: README.md
  • Changelog: NEWS.md

Project organization

joinspy/
├── .github/                <- Continuous integration workflows
├── .gitignore
├── .Rbuildignore
├── joinspy.Rproj
├── DESCRIPTION             <- Package metadata
├── NAMESPACE               <- Function exports and imports
├── LICENSE
├── LICENSE.md
├── NEWS.md
├── README.md
├── _pkgdown.yml
├── R/                      <- R source files
├── man/                    <- Generated documentation
├── vignettes/              <- Long-form documentation
├── tests/
│   └── testthat/           <- Unit tests
└── docs/                   <- pkgdown website (generated)

Contributing workflow

  1. Create a feature branch

    git checkout -b feature/my-feature

  2. Make focused commits with clear messages.

  3. Run tests and checks before committing:

    devtools::test()
devtools::check()

  4. Update documentation with roxygen2 and NEWS.md.

  5. Open a pull request with a short description of your change.

Style guidelines

R code

  • Use descriptive names and consistent indentation.
  • Prefer vectorized operations over loops.
  • Validate inputs early with clear error messages.
  • Document all exported functions with roxygen2.
  • Follow dplyr naming conventions for parameters (x, y, by).

Tests

  • Add or update tests when functionality changes.
  • Keep tests minimal and reproducible.
  • Test with base R data frames, tibbles, and data.tables.

Pull request checklist

Reporting bugs

When reporting an issue, please include: - A minimal reproducible example (reprex) - Output of sessionInfo() - Expected vs. actual results - R and operating system version

By contributing to joinspy, you agree that your code is released under the same license as the package.