diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fd2379980..6d4ce5004 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -94,6 +94,15 @@ TreeTools contains core functionality for tree and split manipulation, designed R -e "devtools::build_vignettes(install = FALSE)" ``` +### Key Dependencies +**Critical**: TreeDist requires these packages to build successfully: +- `ape` (>= 5.0) - Phylogenetic analysis package +- `Rcpp` (>= 1.0.8) - C++ integration (must install before TreeTools) +- `TreeTools` (>= 1.16) - Core tree manipulation (large dependency) +- `Rdpack` (>= 0.7) - Bibliography and citation support +- `shinyjs` - Interactive web applications +- `colorspace` - Color space manipulation + ## Validation **CRITICAL: Always run the full test suite before proposing changes** @@ -112,10 +121,34 @@ TreeTools contains core functionality for tree and split manipulation, designed ```bash R -d "valgrind --tool=memcheck --leak-check=full" --vanilla < memcheck/tests.R ``` + **Note**: Memory check scripts available in `memcheck/` directory: + - `memcheck/tests.R` - Run test suite with valgrind + - `memcheck/all.R` - Run tests, examples, and build vignettes with memory checking ## Validation Scenarios After making code changes, validate functionality by testing core phylogenetic tree operations: +### Essential Pre-commit Validation Steps +1. **Install core dependencies first**: + ```bash + sudo R -e "install.packages(c('ape', 'colorspace', 'Rdpack', 'shinyjs', 'TreeTools'), repos='https://cran.r-project.org/', dependencies=TRUE)" + ``` + +2. **Basic build test** (quick validation): + ```bash + R CMD build . --no-build-vignettes + ``` + +3. **Run linting** (expects GitHub Actions format): + ```bash + R -e "lintr::lint_dir('.')" + ``` + +4. **Load package for testing**: + ```bash + R -e "devtools::load_all()" + ``` + ## Time Expectations & Critical Warnings - **R startup**: ~0.1 seconds @@ -130,9 +163,9 @@ After making code changes, validate functionality by testing core phylogenetic t ## Repository Structure ### Key Directories -- `R/` - R source code (59 R files with 500+ exported functions) -- `src/` - C++ source code requiring compilation (17 C++ files, SystemRequirements: C++17) -- `tests/testthat/` - Test suite (61+ test files) +- `R/` - R source code (31 R files with 500+ exported functions) +- `src/` - C++ source code requiring compilation (14 C++ files, SystemRequirements: C++17) +- `tests/testthat/` - Test suite (30+ test files) - `benchmark/` - Performance benchmarking (10+ benchmark files) - `man/` - Generated documentation (do not edit manually) - `vignettes/` - Package tutorials and documentation @@ -142,9 +175,10 @@ After making code changes, validate functionality by testing core phylogenetic t ### Important Files - `DESCRIPTION` - Package metadata, dependencies, and system requirements - `NAMESPACE` - Generated by roxygen2 (do not edit manually) -- `.lintr` - Code style configuration (follows Google R style guide) - `NEWS.md` - Version history (update for user-facing changes) - `tests/testthat.R` - Test runner entry point +- `inst/_pkgdown.yml` - template for online documentation. + (Check that new functions are registered here, ideally using `@family`) ## Common Tasks ### After Making Changes @@ -179,9 +213,27 @@ After making code changes, validate functionality by testing core phylogenetic t - Missing or inadequate documentation - Missing test coverage for new code +### CI/CD Workflows Available +- **R-CMD-check.yml**: Comprehensive checks on Windows, macOS, Ubuntu across R versions +- **benchmark.yml**: Performance regression testing triggered on PRs +- **memcheck.yml**: Memory checking with valgrind (runs `tests`, `examples`, `vignettes`) +- **ASan.yml**: Address sanitizer checks +- **pkgdown.yml**: Documentation site generation. +- **revdepcheck.yml**: Downstream dependency validation + ## Troubleshooting -- If package won't build: check that all system dependencies are installed -- If tests fail after C++ changes: rebuild package completely -- If documentation is missing: run `devtools::document()` -- If benchmarks fail: performance regressions may need investigation -- Memory issues: use valgrind checking for C++ code validation +### Common Build Issues +- **Missing dependencies**: Install system packages first: `sudo apt install -y libcurl4-openssl-dev libssl-dev libxml2-dev libfontconfig1-dev libharfbuzz-dev libfribidi-dev` +- **Rdpack warnings**: These are normal when `Rdpack` isn't installed but don't prevent building +- **Package won't build**: Install core dependencies: `ape`, `colorspace`, `Rdpack`, `shinyjs`, `TreeTools` +- **TreeTools installation fails**: This is a large dependency - allow 10+ minutes for compilation +- **Tests fail after C++ changes**: rebuild package completely with `R CMD build .` +- **Documentation warnings**: Run `devtools::document()` to regenerate documentation +- **Benchmarks fail**: Performance regressions may need investigation +- **Memory issues**: Use valgrind checking for C++ code validation + +### System Requirements Validation +- R version 4.0+ required (tested with R 4.3.3) +- C++17 compiler support required +- Minimum 2GB RAM recommended for building with dependencies +- Allow 60+ minutes for full dependency installation from scratch diff --git a/.lintr b/.lintr new file mode 100644 index 000000000..d6f9bf143 --- /dev/null +++ b/.lintr @@ -0,0 +1,3 @@ +linters: linters_with_defaults( + object_name_linter(styles = c("CamelCase", "camelCase", "snake_case", "dotted.case")) + )