Thank you for your interest in contributing to staRburst! This document provides guidelines for contributing.
Getting Started
- Fork the repository
- Clone your fork:
git clone https://github.com/yourusername/starburst.git - Create a branch:
git checkout -b feature/your-feature-name - Make your changes
-
IMPORTANT: Run tests:
devtools::test() -
IMPORTANT: Run checks:
devtools::check() - Commit:
git commit -m "Description of changes" - Push:
git push origin feature/your-feature-name - 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.
Set Up Pre-commit Hook (Recommended)
Now every commit will automatically run devtools::check(). The commit will be blocked if there are errors.
Code Style
- Follow the tidyverse style guide
- Use
roxygen2for 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 bytest-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 withplan(starburst),starburst_map()andstarburst_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:
R CMD check --as-cranwith 0 errors / 0 warnings / 0 notes, run with AWS credentials unset.-
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:or the AWS Integration Tests workflow with suite
live-smoke. Every check must PASS. Green offline tests and a green monthlyquickrun do not substitute for this.
Documentation
- Document all exported functions with
roxygen2 - Include
@examplesfor user-facing functions - Update vignettes if adding major features
- Keep README.md up to date
Pull Request Process
- Update NEWS.md with your changes
- Ensure all tests pass
- Update documentation if needed
- Request review from maintainers
- Address review comments
- 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
