Skip to content

AGENTS.md

Latest commit

 

History

History
145 lines (102 loc) · 6.07 KB

AGENTS.md

File metadata and controls

145 lines (102 loc) · 6.07 KB

AI Agent Development Guidelines for igraph

Note: For GitHub Copilot-specific instructions, see .github/copilot-instructions.md.

Project Overview

igraph is an R package for network analysis and graph theory. It provides routines for simple graphs and network analysis, handles large graphs efficiently, and includes functions for generating random and regular graphs, graph visualization, centrality methods, and much more.

Key Technologies

  • Language: R with C/C++ backend (uses the igraph C library)
  • Testing: testthat framework
  • Documentation: roxygen2 with Markdown syntax
  • Code Formatting: air (R formatting tool)
  • Build System: R CMD, devtools, Makefile
  • Code Generation: Stimulus framework (see tools/README.md)

Development Setup

Installation and Dependencies

# Install all dependencies
pak::pak()
# Install build dependencies
pak::pak(dependencies = "Config/Needs/build")

Install and run R

  • When run on GitHub Actions, assume that R, the package in its current state and all dependencies are installed.
  • Only install new packages when needed for implementing new features or tests.
  • Run R -q -e 'devtools::check()' to execute all checks as a final step.

Building and Testing

  • Load package for development: pkgload::load_all()
  • Run tests: testthat::test_local(reporter = "check")
  • Run tests for a single file test-foo.R: testthat::test_local(filter = "foo", reporter = "check")
  • Build package: devtools::build()
  • Check package: devtools::check()
  • Update .Rd documentation: devtools::document()
  • Format code: air format .

Code Style and Documentation

PR and Commit Style

  • IMPORTANT: PR titles end up in NEWS.md grouped by conventional commit label. PRs and commits use the conventional commit style with backticks for code references such as function_call()
  • PRs are generally squashed, a clean history within a PR is not necessary
  • Before resuming work on a PR, always merge the current base branch (typically main)

Comment Style

  • Prefer expressive code over comments where possible
  • Add comments to utility functions that cannot be made immediately obvious
  • Focus comments on explaining the "why" and "how", the "what" should be clear from the code itself
  • Use line breaks after each sentence

R Code Conventions

  • Follow the tidyverse style guide and the tidyverse design guide
  • Use snake_case for new functions and all arguments
  • Use explicit package prefixes (e.g., withr::local_db_connection()) for clarity
  • Maintain consistent indentation (2 spaces) and spacing patterns
  • Use meaningful variable names that reflect context
  • Run air format . before committing changes to ensure consistent formatting
  • Never change deprecated functions
  • Avoid .Call() outside *_impl() in aaa-auto.R

Documentation

  • Use roxygen2 with Markdown syntax for all function documentation
  • Use explicit @description and @details sections, aim for a complete description and move only excess details to @details
  • Use math notation for formulas: \eqn{...} for inline, \deqn{...} for display equations
  • Keep each sentence on its own line in roxygen2 comments for better readability
  • Document all arguments and return values
  • Document internal functions using devtag (work in progress)
  • Link to C documentation using @cdocs tag: #' @cdocs igraph_function_name
  • Always run devtools::document() after updating documentation

Naming Conventions

  • Use max for maximal (graph theory term: a vertex is maximal if no other vertex dominates it) and largest for maximum (the biggest value in a set)

New functions

All new functions must include:

  • Examples
  • Tests
  • Proper documentation, including arguments and return values
  • A concept so that it exists in the pkgdown reference index
  • An "experimental" badge via r lifecycle::badge("experimental")
  • All arguments in snake_case, with documentation and suitable defaults
  • An ellipsis guarded with check_dots_empty() separating mandatory and optional arguments
  • Argument validation using built-in check_*() functions or igraph_arg_match()

For callback functions:

  • The callback is optional, callback = NULL uses a sensible built-in callback or an existing function
  • See tools/AGENTS.md for detailed implementation guide

If exporting a new function from the C library:

  • Ensure it is autogenerated
  • Add tests for the _impl function
  • Name all arguments in all calls to the _impl function
  • For graph constructors, prefer GATTR and GATTR-PARAM in Stimulus over manually assigning attributes

File Structure and Organization

Test Files

  • Test files should align with source files
  • R/name.R → tests/testthat/test-name.R

Generated Files

Do not modify these files directly:

  • src/rinterface.c (generated by Stimulus)
  • R/aaa-auto.R (generated by Stimulus)

Update them using: make -f Makefile-cigraph src/rinterface.c R/aaa-auto.R

See tools/README.md for guidelines on code generation using the Stimulus framework.

Build Artifacts

Do not commit: *.d, *.o, *.so files in src/, and tests/testthat/testthat-problems.rds. These are build artifacts that are regenerated automatically (see src/README.md for details on dependency tracking).

Careful with changes to *.dd, keep system headers out, only expect changes if new source files are added or their local dependencies change.

Testing

  • Add test cases for all new functionality
  • For newly created autogenerated functions, always add a test to test-aaa-auto.R
  • Test file naming should mirror source file naming
  • Implement both structured and snapshot tests. For the latter, ensure stability by setting a random seed and calling local_igraph_options(print.id = FALSE) if graph IDs are involved.
  • When testing error behavior, prefer snapshot tests.
  • Run tests frequently during development and at the end: testthat::test_local(reporter = "check")
  • Run devtools::check() as a final step to ensure all checks pass.