Skip to contents

Thank you for your interest in contributing to staRburst! This document provides guidelines for contributing.

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/yourusername/starburst.git
  3. Create a branch: git checkout -b feature/your-feature-name
  4. Make your changes
  5. IMPORTANT: Run tests: devtools::test()
  6. IMPORTANT: Run checks: devtools::check()
  7. Commit: git commit -m "Description of changes"
  8. Push: git push origin feature/your-feature-name
  9. Open a Pull Request

⚠️ Before Pushing - Run Checks Locally!

Always run R CMD check locally before pushing to avoid CI failures and wasted GitHub Actions minutes.

# Enable automatic checking before every commit
git config core.hooksPath .githooks

Now every commit will automatically run devtools::check(). The commit will be blocked if there are errors.

Manual Check Before Push

# Quick check
Rscript -e "devtools::check()"

# Or full check (what CI runs)
R CMD build .
R CMD check --as-cran starburst_*.tar.gz
git commit --no-verify -m "Your message"

Development Setup

# Install development dependencies
install.packages(c("devtools", "testthat", "roxygen2", "pkgdown"))

# Load package for development
devtools::load_all()

# Run tests
devtools::test()

# Build documentation
devtools::document()

# Check package
devtools::check()

Code Style

  • Follow the tidyverse style guide
  • Use roxygen2 for documentation
  • Write tests for new functions
  • Keep functions focused and modular

Testing

  • Write tests for all new functionality
  • Place tests in tests/testthat/test-*.R
  • Use descriptive test names
  • Mock AWS API calls when possible, but never mock the client/worker seam: anything that changes how tasks are serialized, submitted, executed by inst/templates/worker.R, or read back must be covered by the round-trip harness (tests/testthat/helper-roundtrip.R, used by test-roundtrip.R). It runs the shipped worker script against an in-memory S3 and a fake ECS that rejects requests real EC2 rejects. Releases 0.3.0-0.3.10 shipped with plan(starburst), starburst_map() and starburst_cluster() broken on real workers because every test mocked that seam.
test_that("function does what it should", {
  expect_equal(my_function(1), 2)
})

Releasing

A release (tag, GitHub Release, CRAN submission) requires, on the release commit:

  1. R CMD check --as-cran with 0 errors / 0 warnings / 0 notes, run with AWS credentials unset.

  2. A passing live smoke test on real EC2: every public entry point (plan(starburst) + future.apply, starburst_map(), starburst_cluster(), starburst_session()) end to end:

    timeout 45m Rscript tools/live-smoke.R

    or the AWS Integration Tests workflow with suite live-smoke. Every check must PASS. Green offline tests and a green monthly quick run do not substitute for this.

Documentation

  • Document all exported functions with roxygen2
  • Include @examples for user-facing functions
  • Update vignettes if adding major features
  • Keep README.md up to date

Pull Request Process

  1. Update NEWS.md with your changes
  2. Ensure all tests pass
  3. Update documentation if needed
  4. Request review from maintainers
  5. Address review comments
  6. Merge when approved

Areas for Contribution

See issues for specific tasks.

Priority areas: - Docker image building implementation - Additional serialization methods - Performance optimization - Documentation improvements - Example workflows

Questions?

  • Open an issue for bugs or feature requests
  • Use discussions for questions
  • Email maintainers for sensitive issues

Code of Conduct

Be respectful and inclusive. We want staRburst to be welcoming to all contributors.