From a7098f61da872dab01aaeff3c1e40c5b9dba9956 Mon Sep 17 00:00:00 2001 From: Mike-Hanna Date: Thu, 23 Oct 2025 12:45:15 -0400 Subject: [PATCH 1/4] add instructions for R programming language --- README.instructions.md | 1 + instructions/r.instructions.md | 118 +++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 instructions/r.instructions.md diff --git a/README.instructions.md b/README.instructions.md index acc610f6..2957e2a9 100644 --- a/README.instructions.md +++ b/README.instructions.md @@ -97,6 +97,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Python MCP Server Development](instructions/python-mcp-server.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython-mcp-server.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython-mcp-server.instructions.md) | Instructions for building Model Context Protocol (MCP) servers using the Python SDK | | [Quarkus](instructions/quarkus.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus.instructions.md) | Quarkus development standards and instructions | | [Quarkus MCP Server](instructions/quarkus-mcp-server-sse.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus-mcp-server-sse.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fquarkus-mcp-server-sse.instructions.md) | Quarkus and MCP Server with HTTP SSE transport development standards and instructions | +| [R Programming Language Instructions](instructions/r.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fr.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fr.instructions.md) | R language and document formats (R, Rmd, Quarto): coding standards and Copilot guidance for idiomatic, safe, and consistent code generation. | | [ReactJS Development Instructions](instructions/reactjs.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Freactjs.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Freactjs.instructions.md) | ReactJS development standards and best practices | | [Ruby MCP Server Development Guidelines](instructions/ruby-mcp-server.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-mcp-server.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Ruby using the official MCP Ruby SDK gem. | | [Ruby on Rails](instructions/ruby-on-rails.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-on-rails.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fruby-on-rails.instructions.md) | Ruby on Rails coding conventions and guidelines | diff --git a/instructions/r.instructions.md b/instructions/r.instructions.md new file mode 100644 index 00000000..d4b9a1e5 --- /dev/null +++ b/instructions/r.instructions.md @@ -0,0 +1,118 @@ +--- +description: "R language and document formats (R, Rmd, Quarto): coding standards and Copilot guidance for idiomatic, safe, and consistent code generation." +applyTo: "**/*.{R,r,Rmd,rmd,qmd}" +--- + +# R Programming Language Instructions + +## Purpose + +Help GitHub Copilot generate idiomatic, safe, and maintainable R code across projects. + +## Core Conventions + +- **Match the project’s style.** If the file shows a preference (tidyverse vs. base R, `%>%` vs. `|>`), follow it. +- **Prefer clear, vectorized code.** Keep functions small and avoid hidden side effects. +- **Qualify non-base functions in examples/snippets**, e.g., `dplyr::mutate()`, `stringr::str_detect()`. +In project code, using `library()` is acceptable when that’s the repo norm. +- **Naming:** `lower_snake_case` for objects/files; avoid dots in names. +- **Side effects:** Never call `setwd()`; prefer project-relative paths (e.g., `here::here()`). +- **Reproducibility:** Set seeds locally around stochastic operations using `withr::with_seed()`. +- **Validation:** Validate and constrain user inputs; use typed checks and allowlists where possible. +- **Safety:** Avoid `eval(parse())`, unvalidated shell calls, and unparameterized SQL. + +### Pipe Operators + +- **Native pipe `|>` (R ≥ 4.1.0):** Prefer in R ≥ 4.1 (no extra dependency). +- **Magrittr pipe `%>%`:** Continue using in projects already committed to magrittr or when you need features like `.`, `%T>%`, or `%$%`. +- **Be consistent:** Don't mix `|>` and `%>%` within the same script unless there's a clear technical reason. + +## Performance Considerations + +- **Large datasets:** consider `data.table`; benchmark with your workload. +- **dplyr compatibility:** Use `dtplyr` to write dplyr syntax that translates to data.table operations automatically for performance gains. +- **Profiling:** Use `profvis::profvis()` to identify performance bottlenecks in your code. Profile before optimizing. +- **Caching:** Use `memoise::memoise()` to cache expensive function results. Particularly useful for repeated API calls or complex computations. +- **Vectorization:** Prefer vectorized operations over loops. Use `purrr::map_*()` family or `apply()` family for remaining iteration needs. + +## Tooling & Quality + +- **Formatting:** `styler` (tidyverse style), two-space indents, ~100-char lines. +- **Linting:** `lintr` configured via `.lintr`. +- **Pre-commit:** consider `precommit` hooks to lint/format automatically. +- **Docs:** roxygen2 for exported functions (`@param`, `@return`, `@examples`). +- **Tests:** prefer small, pure, composable functions that are easy to unit test. +- **Dependencies:** manage with `renv`; snapshot after adding packages. +- **Paths:** prefer `fs` and `here` for portability. + +## Data Wrangling & I/O + +- **Data frames:** prefer tibbles in tidyverse-heavy files; otherwise base `data.frame()` is fine. +- **Iteration:** use `purrr` in tidyverse code. In base-style code, prefer type-stable, vectorized patterns such as `vapply()` + (for atomic outputs) or `Map()` (for elementwise operations) instead of explicit `for` loops when they improve clarity or performance. +- **Strings & Dates:** use `stringr`/`lubridate` where already present; otherwise use clear base helpers (e.g., `nchar()`, `substr()`, `as.Date()` with explicit format). +- **I/O:** prefer explicit, typed readers (e.g., `readr::read_csv()`); make parsing assumptions explicit. + +## Plotting + +- Prefer `ggplot2` for publication-quality plots. Keep layers readable and label axes and units. + +## Error Handling + +- In tidyverse contexts, use `rlang::abort()` / `rlang::warn()` for structured conditions; in base-only code, use `stop()` / `warning()`. +- For recoverable operations: +- Use `purrr::possibly()` when you want a typed fallback value of the same type (simpler). +- Use `purrr::safely()` when you need to capture both results and errors for later inspection or logging. +- Use `tryCatch()` in base R for fine-grained control or compatibility with non-tidyverse code. +- Prefer consistent return structures—typed outputs for normal flows, structured lists only when error details are required. + +## Security Best Practices + +- **Command execution:** Prefer `processx::run()` or `sys::exec_wait()` over `system()`; validate and sanitize all arguments. +- **Database queries:** Use parameterized `DBI` queries to prevent SQL injection. +- **File paths:** Normalize and sanitize user-provided paths (e.g., `fs::path_sanitize()`), and validate against allowlists. +- **Credentials:** Never hardcode secrets. Use env vars (`Sys.getenv()`), config outside VCS, or `keyring`. + +## Shiny + +- Modularize UI and server logic for non-trivial apps. Use `eventReactive()` / `observeEvent()` for explicit dependencies. +- Validate inputs with `req()` and clear, user-friendly messages. +- Use connection pooling (`pool`) for databases; avoid long-lived global objects. +- Isolate expensive computations and prefer `reactiveVal()` / `reactiveValues()` for small state. + +## R Markdown / Quarto + +- Keep chunks focused; prefer explicit chunk options (`echo`, `message`, `warning`). +- Avoid global state; prefer local helpers. Use `withr::with_seed()` for deterministic chunks. + +## Copilot-Specific Guidance + +- If the current file uses tidyverse, **suggest tidyverse-first patterns** (e.g., `dplyr::across()` instead of superseded verbs). +If base-R style is present, **use base idioms**. +- Qualify non-base calls in suggestions (e.g., `dplyr::mutate()`). +- Suggest vectorized or tidy solutions over loops when idiomatic. +- Prefer small helper functions over long pipelines. +- When multiple approaches are equivalent, prefer readability and type stability and explain the trade-offs. + +--- + +## Minimal Examples + +```r +# Base R variant +scores <- data.frame(id = 1:5, x = c(1, 3, 2, 5, 4)) +safe_log <- function(x) tryCatch(log(x), error = function(e) NA_real_) +scores$z <- vapply(scores$x, safe_log, numeric(1)) + +# Tidyverse variant (if this file uses tidyverse) +result <- tibble::tibble(id = 1:5, x = c(1, 3, 2, 5, 4)) |> +dplyr::mutate(z = purrr::possibly(log, otherwise = NA_real_)(x)) |> +dplyr::filter(z > 0) + +# Example reusable helper with roxygen2 doc +#' Compute the z-score of a numeric vector +#' @param x A numeric vector +#' @return Numeric vector of z-scores +#' @examples z_score(c(1, 2, 3)) +z_score <- function(x) (x - mean(x, na.rm = TRUE)) / stats::sd(x, na.rm = TRUE) +``` From 7ca6f6bd4ce889074906e838cf0a500892b604bb Mon Sep 17 00:00:00 2001 From: Mike-Hanna Date: Thu, 23 Oct 2025 13:15:44 -0400 Subject: [PATCH 2/4] copilot review updates --- instructions/r.instructions.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/instructions/r.instructions.md b/instructions/r.instructions.md index d4b9a1e5..d4689b14 100644 --- a/instructions/r.instructions.md +++ b/instructions/r.instructions.md @@ -1,6 +1,6 @@ --- -description: "R language and document formats (R, Rmd, Quarto): coding standards and Copilot guidance for idiomatic, safe, and consistent code generation." -applyTo: "**/*.{R,r,Rmd,rmd,qmd}" +description: 'R language and document formats (R, Rmd, Quarto): coding standards and Copilot guidance for idiomatic, safe, and consistent code generation.' +applyTo: '**/*.{R,r,Rmd,rmd,qmd}' --- # R Programming Language Instructions @@ -13,8 +13,7 @@ Help GitHub Copilot generate idiomatic, safe, and maintainable R code across pro - **Match the project’s style.** If the file shows a preference (tidyverse vs. base R, `%>%` vs. `|>`), follow it. - **Prefer clear, vectorized code.** Keep functions small and avoid hidden side effects. -- **Qualify non-base functions in examples/snippets**, e.g., `dplyr::mutate()`, `stringr::str_detect()`. -In project code, using `library()` is acceptable when that’s the repo norm. +- **Qualify non-base functions in examples/snippets**, e.g., `dplyr::mutate()`, `stringr::str_detect()`. In project code, using `library()` is acceptable when that’s the repo norm. - **Naming:** `lower_snake_case` for objects/files; avoid dots in names. - **Side effects:** Never call `setwd()`; prefer project-relative paths (e.g., `here::here()`). - **Reproducibility:** Set seeds locally around stochastic operations using `withr::with_seed()`. @@ -48,7 +47,7 @@ In project code, using `library()` is acceptable when that’s the repo norm. ## Data Wrangling & I/O - **Data frames:** prefer tibbles in tidyverse-heavy files; otherwise base `data.frame()` is fine. -- **Iteration:** use `purrr` in tidyverse code. In base-style code, prefer type-stable, vectorized patterns such as `vapply()` +- **Iteration:** use `purrr` in tidyverse code. In base-style code, prefer type-stable, vectorized patterns such as `vapply()` (for atomic outputs) or `Map()` (for elementwise operations) instead of explicit `for` loops when they improve clarity or performance. - **Strings & Dates:** use `stringr`/`lubridate` where already present; otherwise use clear base helpers (e.g., `nchar()`, `substr()`, `as.Date()` with explicit format). - **I/O:** prefer explicit, typed readers (e.g., `readr::read_csv()`); make parsing assumptions explicit. @@ -87,8 +86,7 @@ In project code, using `library()` is acceptable when that’s the repo norm. ## Copilot-Specific Guidance -- If the current file uses tidyverse, **suggest tidyverse-first patterns** (e.g., `dplyr::across()` instead of superseded verbs). -If base-R style is present, **use base idioms**. +- If the current file uses tidyverse, **suggest tidyverse-first patterns** (e.g., `dplyr::across()` instead of superseded verbs). If base-R style is present, **use base idioms**. - Qualify non-base calls in suggestions (e.g., `dplyr::mutate()`). - Suggest vectorized or tidy solutions over loops when idiomatic. - Prefer small helper functions over long pipelines. @@ -106,7 +104,7 @@ scores$z <- vapply(scores$x, safe_log, numeric(1)) # Tidyverse variant (if this file uses tidyverse) result <- tibble::tibble(id = 1:5, x = c(1, 3, 2, 5, 4)) |> -dplyr::mutate(z = purrr::possibly(log, otherwise = NA_real_)(x)) |> +dplyr::mutate(z = purrr::map_dbl(x, purrr::possibly(log, otherwise = NA_real_))) |> dplyr::filter(z > 0) # Example reusable helper with roxygen2 doc From 3c57a1c2b0c78873a05efb73e43f3e4b7235543d Mon Sep 17 00:00:00 2001 From: Mike-Hanna Date: Thu, 23 Oct 2025 13:19:52 -0400 Subject: [PATCH 3/4] applyTo syntax update --- instructions/r.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/instructions/r.instructions.md b/instructions/r.instructions.md index d4689b14..11081e8c 100644 --- a/instructions/r.instructions.md +++ b/instructions/r.instructions.md @@ -1,6 +1,6 @@ --- description: 'R language and document formats (R, Rmd, Quarto): coding standards and Copilot guidance for idiomatic, safe, and consistent code generation.' -applyTo: '**/*.{R,r,Rmd,rmd,qmd}' +applyTo: '**/*.R, **/*.r, **/*.Rmd, **/*.rmd, **/*.qmd' --- # R Programming Language Instructions From f7a52c5fd456b97553b0037177764d63876fd9ef Mon Sep 17 00:00:00 2001 From: Mike-Hanna Date: Thu, 23 Oct 2025 13:25:23 -0400 Subject: [PATCH 4/4] copilot nitpicks --- instructions/r.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/instructions/r.instructions.md b/instructions/r.instructions.md index 11081e8c..25378324 100644 --- a/instructions/r.instructions.md +++ b/instructions/r.instructions.md @@ -48,7 +48,7 @@ Help GitHub Copilot generate idiomatic, safe, and maintainable R code across pro - **Data frames:** prefer tibbles in tidyverse-heavy files; otherwise base `data.frame()` is fine. - **Iteration:** use `purrr` in tidyverse code. In base-style code, prefer type-stable, vectorized patterns such as `vapply()` - (for atomic outputs) or `Map()` (for elementwise operations) instead of explicit `for` loops when they improve clarity or performance. + (for atomic outputs) or `Map()` (for elementwise operations) instead of explicit `for` loops when they improve clarity or performance. - **Strings & Dates:** use `stringr`/`lubridate` where already present; otherwise use clear base helpers (e.g., `nchar()`, `substr()`, `as.Date()` with explicit format). - **I/O:** prefer explicit, typed readers (e.g., `readr::read_csv()`); make parsing assumptions explicit.