Skip to content

copilot-instructions.md

Latest commit

 

History

History
244 lines (195 loc) · 9.32 KB

copilot-instructions.md

File metadata and controls

244 lines (195 loc) · 9.32 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, litedown) - 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
  • Use %==% (from testit) instead of == to test for strict equality
  • Never use ::: to access internal functions in tests; testit exposes internal functions automatically, so call them directly

Rendering Example Rmd Files

All examples/*.Rmd files are rendered using litedown, not rmarkdown. Never use rmarkdown::render() — it will produce incorrect output or fail.

To render an Rmd file to HTML (e.g., for inspection or headless browser testing):

Rscript -e 'litedown::fuse("path/to/foo.Rmd")'
# output: path/to/foo.html

The GitHub Pages site is built by the yihui/litedown/site action, which calls litedown::fuse() for every Rmd in the repo.

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. The workflow is:

  1. Render the Rmd to HTML first using litedown (see above).
  2. Open the HTML in a headless browser (Puppeteer or Playwright).
  3. Verify that:
    • The chart container element exists in the DOM.
    • The G2 chart renders without JavaScript errors.
    • No warnings or errors appear in the browser console.

Submitting Plot Changes in PRs

When fixing or changing plot examples, always submit screenshots of the plots as PR comments so reviewers can see the visual results. Take screenshots in headless browsers (Playwright or Puppeteer) and attach them to the PR.

G2 Reference

When dealing with issues that you cannot solve easily, you should dig into G2's source code and documentation, which have been checked out to the directory G2 under the root directory for you. Use that as the source of truth.

If you have consulted the source repository and documentation but still cannot solve a problem raised in a PR, file a GitHub issue for that problem to keep track of it. The issue should clearly describe what the problem is, and why you cannot solve it.

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_() and helpers (scale_x(), scale_y(), etc.)
  • coordinate.R - coord_(), coord_transpose()
  • interact.R - interact()
  • theme.R - theme_() and theme shortcuts
  • transform.R - transform_()
  • facet.R - facet_rect(), facet_circle()
  • animate.R - animate()
  • component.R - axis_(), legend_(), title_(), tooltip_(), labels_(), style_mark(), slider_(), scrollbar_() and helpers
  • render.R - build_config(), chart_html(), print.g2(), knit_print.g2(), record_print.g2()

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 (except for v0.1). Do NOT add NEWS entries while the package is still at v0.1 — the initial release description is sufficient.

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.
  10. Implicit NULL: Don't write if (cond) foo else NULL; the else NULL is unnecessary since R's if without else already returns NULL.
  11. Return NULL: Never write return(NULL); use return() instead since R functions return NULL by default when no value is given.

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. MANDATORY: Merge latest main before pushing: Before pushing to a branch or PR, always pull and merge the latest main branch. If there are merge conflicts, resolve them before pushing.
  5. 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
  6. NEVER BREAK CI: Breaking CI is completely unacceptable. If CI fails, you must immediately fix it.
  7. Never commit binary files: Avoid version-controlling binary files, especially automatically generated ones.
  8. Testing: Use testit assertions with proper error handling
  9. Update NEWS.md: When making changes, make sure to update NEWS.md accordingly to document what changed — except for v0.1 (do NOT add individual change entries for the initial release). 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') |>
  scale_x(type = 'log') |>
  theme_('dark') |>
  title_('Motor Trend Cars')