Skip to contents

Contributing to phylobuild

Source: CONTRIBUTING.md

Thank you for your interest in contributing to phylobuild! This document provides guidance for developers who want to build, test, and contribute to the package.

Prerequisites

You’ll need the following R packages for development:

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

Development Workflow

Loading the Package for Development

Use devtools::load_all() to load the package source code without installing it. This is the fastest way to test changes during development:

# From the package root directory
devtools::load_all()

# Now you can use package functions directly
data(primates)
tree <- fast_nj(primates)

After making changes to R code, simply run load_all() again to reload.

Note: If you modify C++ code in src/, you’ll need to recompile:

devtools::load_all(recompile = TRUE)

Running Tests

Run the test suite with:

devtools::test()

Or run specific test files:

devtools::test(filter = "fast_nj")

From the terminal:

Rscript -e 'devtools::test()'

Updating Documentation

After modifying roxygen2 comments (the #' blocks), regenerate the .Rd files:

devtools::document()

This also updates the NAMESPACE file.

Building the pkgdown Website

Build the documentation website locally:

pkgdown::build_site()

The site will be generated in the docs/ directory. Open docs/index.html in a browser to preview.

To build just specific parts:

pkgdown::build_home()       # Just the home page
pkgdown::build_reference()  # Just the function reference
pkgdown::build_articles()   # Just the vignettes

Building and Checking the Package

Build the source package (.tar.gz)

R CMD build .

This creates phylobuild_x.y.z.tar.gz in the current directory.

Run R CMD check

The standard way to check an R package for issues:

R CMD build .
R CMD check phylobuild_0.1.0.tar.gz

For CRAN-like checks (stricter):

R CMD check --as-cran phylobuild_0.1.0.tar.gz

Or from within R:

devtools::check()

Install from source

R CMD INSTALL .

Or with devtools:

devtools::install()

Regenerating Example Data

If you need to regenerate the example datasets:

source("data-raw/make_example_data.R")

This recreates data/primates.rda and data/sim_100.rda.

Project Structure

phylobuild/
├── R/                    # R source files
│   ├── phylobuild.R        # Main fast_nj() function
│   ├── RcppExports.R     # Auto-generated Rcpp bindings
│   └── data.R            # Dataset documentation
├── src/                  # C++ source files (decenttree library)
│   ├── phylobuild.cpp      # R/C++ interface
│   ├── starttree.cpp     # Algorithm registry
│   ├── bionj2.cpp        # NJ/BIONJ implementations
│   └── ...
├── data/                 # Package datasets (.rda files)
├── data-raw/             # Scripts to generate datasets
├── man/                  # Documentation (.Rd files, auto-generated)
├── tests/testthat/       # Unit tests
├── vignettes/            # Long-form documentation
├── inst/
│   ├── CITATION          # Citation information
│   └── benchmarks/       # Benchmark scripts
└── _pkgdown.yml          # Website configuration

Common Tasks

Adding a New Function

  1. Add the function to an .R file in R/
  2. Add roxygen2 documentation above the function
  3. Run devtools::document() to generate the .Rd file
  4. Add tests in tests/testthat/
  5. Run devtools::test() to verify

Modifying C++ Code

  1. Edit files in src/
  2. Run devtools::load_all(recompile = TRUE)
  3. If you add new exported functions, run Rcpp::compileAttributes()
  4. Run devtools::check() to ensure it compiles on a clean build

Updating the Vignette

  1. Edit vignettes/phylobuild.Rmd
  2. Preview with devtools::build_vignettes()
  3. Rebuild the pkgdown site with pkgdown::build_site()

Code Style

  • Use roxygen2 for all documentation
  • Follow the tidyverse style guide where practical
  • Include examples in function documentation
  • Write tests for new functionality

Getting Help

  • Open an issue on GitHub for bugs or feature requests
  • See the pkgdown site for documentation

License

By contributing to phylobuild, you agree that your contributions will be licensed under the GPL (>= 2) license.