Skip to content

copilot-instructions.md

Latest commit

 

History

History
194 lines (156 loc) · 6.99 KB

copilot-instructions.md

File metadata and controls

194 lines (156 loc) · 6.99 KB

gglite - Repository Instructions for Copilot

Repository Overview

This is an R package that provides a lightweight interface to the AntV G2 JavaScript visualization library with a ggplot2-style API. It supports rendering in R Markdown, litedown, Shiny, and standalone HTML previews.

Project Type: R package Languages: R, JavaScript (via CDN) Size: Small repository (~15 R source files) Target Runtime: R (>= 3.5.0)

Build and Test Instructions

Prerequisites

Note: R is automatically installed via .github/copilot-setup-steps.yml when working with GitHub Copilot. For manual setup:

  • R (>= 3.5.0) - available via copilot-setup-steps.yml
  • R package dependencies (testit, roxygen2, xfun) - available via copilot-setup-steps.yml

For testing on Linux manually: If not using Copilot's automated setup, install the latest R from CRAN, not from Debian/Ubuntu official repositories. Follow instructions at https://cran.r-project.org/bin/linux/ubuntu to ensure you're testing with the most recent R version that users will have.

Bootstrap and Build Sequence

  1. Build the R package:

    R CMD build .

  2. Install the package:

    R CMD INSTALL gglite_*.tar.gz

  3. Run tests:

    R CMD check gglite_*.tar.gz --no-manual

    or directly:

    Rscript tests/test-all.R
    • Tests use the testit package
    • All tests should pass without errors

Testing Conventions

  • Tests are in tests/testit/test-gglite.R
  • Use testit package for assertions
  • Always wrap test conditions in {}: assert('message', {})
  • Use has_error() instead of tryCatch() for error testing
  • Load the package with library(gglite) before testing

Testing Plots in Headless Browsers

Since gglite generates HTML/JavaScript visualizations, plots must be tested in headless browsers to make sure they can be rendered correctly and produce no errors in the browser console. Use tools such as Puppeteer or Playwright to open the generated HTML and verify that:

  1. The chart container element exists in the DOM.
  2. The G2 chart renders without JavaScript errors.
  3. No warnings or errors appear in the browser console.

Project Structure

Key Files and Directories

Root level:

  • DESCRIPTION - R package metadata
  • NAMESPACE - R package namespace (auto-generated by roxygen2)
  • NEWS.md - Changelog
  • README.md - Package documentation
  • examples/ - Rmd example files for each chart component

R code (R/):

  • gglite.R - Core: package doc, CDN URLs, g2(), encode(), annotate_df()
  • mark.R - All 35 mark (geometry) functions
  • scale.R - scale_of()
  • coordinate.R - coordinate(), coord_transpose()
  • interact.R - interact()
  • theme.R - theme_of()
  • transform.R - transform_of()
  • facet.R - facet_rect(), facet_circle()
  • animate.R - animate()
  • component.R - axis_of(), legend_of(), title_of(), tooltip_of(), labels_of(), style_mark(), slider_of(), scrollbar_of()
  • render.R - build_config(), chart_html(), preview(), print.g2(), knit_print.g2(), record_print.g2(), render_shiny()

Tests (tests/):

  • test-all.R - Entry point
  • testit/test-gglite.R - All package tests using testit framework

CI/CD Configuration

GitHub Actions (.github/workflows/):

  • R-CMD-check.yaml - Runs R CMD check on multiple platforms
  • copilot-setup-steps.yml - Sets up the environment for Copilot
  • github-pages.yml - Builds and deploys the package site via litedown

Validation Steps

Before submitting changes:

  1. Run R CMD build . to build the package
  2. Run R CMD check gglite_*.tar.gz --no-manual to validate
  3. Ensure all tests pass: Rscript tests/test-all.R
  4. Check GitHub Actions status for multi-platform validation
  5. Update NEWS.md to document your changes

Important Conventions

R Code Style

  1. Assignment: Use = instead of <- for assignment
  2. Strings: Use single quotes for strings (e.g., 'text')
  3. Indentation: Use 2 spaces (not 4 spaces or tabs)
  4. Compact code: Avoid {} for single-expression if statements; prefer compact forms when possible
  5. Roxygen documentation: Don't use @description or @details explicitly — just write the description text directly after the title. Don't use @title either.
  6. Examples: Avoid \dontrun{} unless absolutely necessary. Prefer runnable examples that can be tested automatically.
  7. Function definitions: For functions with many arguments, break the line right after the opening (, indent arguments by 2 spaces, and try to wrap them at 80-char width.
  8. Re-wrap code: Always re-wrap the code after making changes to maintain consistent formatting and line length.
  9. JavaScript in R: Use const and arrow functions (=>) in JS, type="module" for inline scripts, defer for external scripts.

Variables Are Character Strings

gglite does NOT use non-standard evaluation (NSE). Variables are specified as character strings, e.g., g2(mtcars, x = 'mpg', y = 'hp').

Testing Conventions

  1. Use testit properly: Write all test conditions in (), use %==% to test for identical(), and test conditions can return vectors. 
    assert("test description", {
  (length(result) %==% 3L)
  (file.exists(result))
})

Build and Package Conventions

  1. Always re-roxygenize: Run roxygen2::roxygenize() after changing any roxygen documentation to update man files
  2. MANDATORY: R CMD check before EVERY commit: You MUST run R CMD check successfully before submitting ANY code changes.
  3. MANDATORY: Wait for CI to be green: After pushing code, you MUST wait for GitHub Actions CI to complete successfully before claiming the task is done.
  4. Bump version in PRs: Bump the patch version number in DESCRIPTION once per PR (on the first commit or when you first make changes), not on every commit to the PR
  5. NEVER BREAK CI: Breaking CI is completely unacceptable. If CI fails, you must immediately fix it.
  6. Never commit binary files: Avoid version-controlling binary files, especially automatically generated ones.
  7. Testing: Use testit assertions with proper error handling
  8. Update NEWS.md: When making changes, make sure to update NEWS.md accordingly to document what changed. The first heading in NEWS.md always represents the dev version and must be of the form # PKG x.y where PKG is the package name and x.y is the next version to be released to CRAN (note: x.y, not x.y.0). Usually y is bumped from the current minor version, e.g., if the current dev version is 1.8.3, the next CRAN release is expected to be 1.9.

Package API

The main entry point is g2() which creates a chart object, then pipe operators (|>) chain mark, scale, coordinate, interaction, theme, and component functions:

g2(mtcars, x = 'mpg', y = 'hp') |>
  mark_point() |>
  scale_of('x', type = 'log') |>
  theme_of('dark') |>
  title_of('Motor Trend Cars')