Skip to contents

Contribution Guidelines

Source: CONTRIBUTING.md

First of all, thank you very much for taking the time to contribute to the taxify project!

This document provides guidelines for contributing to taxify—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 (CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code and maintain a respectful, inclusive environment.

Installation

This installation guide is focused on development. For regular installation, please see the README.

Obtaining the source

Clone the taxify repository:

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

Setting up your R environment

taxify is a runtime-only R package. All heavy computation runs in the vectra C11 columnar engine, and all backbone/enrichment building lives in the sibling package taxifydb.

  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"))

    taxify itself depends on vectra, curl, jsonlite, and rlang. Some features use optional packages listed under Suggests in DESCRIPTION (for example taxifydb for build-from-source, openxlsx2, sf, terra).

  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

taxify 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()

Run a subset of tests during development:

testthat::test_dir("tests/testthat")
testthat::test_file("tests/testthat/test-clean.R")

Guidelines: - Keep tests fast and reproducible. - Use set.seed() for random data. - Prefer the bundled example database (inst/exampledb/) over downloading real backbones, so tests stay offline and deterministic. - Include edge cases and expected failures.

Documentation

Install dependencies

install.packages(c("rmarkdown", "knitr", "pkgdown"))

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. Open docs/index.html in your browser to view it.

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

taxify/
├── .github/                <- Continuous integration workflows
├── .gitignore
├── .Rbuildignore
├── DESCRIPTION             <- Package metadata
├── NAMESPACE               <- Function exports and imports
├── LICENSE
├── NEWS.md
├── README.md
├── _pkgdown.yml
├── R/                      <- R source files (matching, backends, enrichments)
├── man/                    <- Generated documentation
├── inst/                   <- Installed files (manifest, example database)
├── vignettes/              <- Long-form documentation and usage examples
├── tests/
│   └── testthat/           <- Unit tests
└── docs/                   <- pkgdown website (generated)

Backbones, enrichments, and taxifydb

taxify is the lean runtime: S3 generics, matching logic, enrichment joins, and cache management. It reads pre-built .vtr files downloaded from GitHub Releases via the manifest.

All download/parse/normalize/index logic for backbones and enrichments lives in taxifydb. When a user needs to build from source, taxify delegates to taxifydb::build_<name>(). Without taxifydb installed, taxify still works fully against the pre-built .vtr downloads.

If you want to add a backbone or an enrichment, the canonical build pipeline lives in taxifydb; the taxify side is a thin constructor plus a taxify_download shim (backbones) or an add_<name>() wrapper around enrich_simple() / enrich_by_group() (enrichments). See the file map in CLAUDE.md for the exact wiring.

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. Update vignettes/examples if user-facing behavior changes.

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

  7. Respond to review feedback constructively.

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.
  • Keep matching logic in the shared engine (R/backend.R); avoid per-backend copies of exact/fuzzy matching.

Tests

  • Add or update tests when functionality changes.
  • Keep tests minimal, offline, and reproducible.
  • Prefer the bundled example database over network access.

Pull request checklist

Reporting bugs

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

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