contributor guidelines (add to CONTRIBUTING.md?)

[mdsumner]

There's no priority on this at all, just I generated the summary and it might be of interest. Thanks!

In #874 @ctoney provided super helpful feedback to polish the PR in terms of style and documentation details in line with the rest of the package. This could form the basis of a more detailed section in CONTRIBUTING.md?

Some questions:

• should a contributor run lintr::lint_package() and aim to fold that in?

Adding methods and functions

This section describes how to add new functionality to gdalraster, whether as a method on an Rcpp module class (like GDALRaster or GDALVector) or as a standalone function.

Adding a method to GDALRaster or GDALVector

The exposed C++ classes use Rcpp modules. Adding a new method requires changes in multiple locations:

1. Implement the C++ method in the class (e.g., src/gdalraster.cpp):

Rcpp::RObject GDALRaster::myNewMethod(int arg1, int arg2) const {
    checkAccess_(GA_ReadOnly);  // use internal helpers for consistency
    // implementation...
}

Use checkAccess_(GA_ReadOnly) or checkAccess_(GA_Update) rather than inline open-checks, for consistency and easier future updates.

2. Register the method in the Rcpp module definition (bottom of src/gdalraster.cpp):

.const_method("myNewMethod", &GDALRaster::myNewMethod,
              "Brief description of what this method does")

Use .const_method() for read-only operations, .method() for operations that modify state, and .field() or .field_readonly() for exposed member variables. See the [Rcpp Modules vignette](https://cran.r-project.org/web/packages/Rcpp/vignettes/Rcpp-modules.pdf) (sections 2.2.3–2.2.6) for full details on .constructor(), .method(), .const_method(), .field(), .property(), and .finalizer().

3. Document in R (R/gdalraster.R) in two places:

• Usage section (~line 42+): Add the method signature to match the order in Details
• Details section: Add roxygen documentation with @description, parameters, return value, and examples

The Usage section lists all method signatures in a non-standard format to accommodate Rcpp exposed classes in R's documentation system. Copy the signature style from similar existing methods.

4. Add explicit includes where needed. If using R internals like R_RGB/R_RGBA:

// for R_RGB / R_RGBA
#include <R_ext/GraphicsEngine.h>

Adding a standalone function

Standalone functions go in the appropriate R file under R/ (e.g., R/gdalraster_proc.R for raster processing functions):

1. Implement the function with roxygen documentation:

#' Brief title
#'
#' @description
#' Longer description of what this function does.
#'
#' @param arg1 Description of first argument.
#' @returns Description of return value.
#' @examples
#' # example code
#' @export
my_new_function <- function(arg1, arg2) {
    # implementation
}

2. Register in _pkgdown.yml under the appropriate subtitle section. For example, display functions go in the "Raster display" section:

- subtitle: Raster display
- contents:
  - plot_raster
  - read_ds
  - my_new_function

3. Run devtools::document() to generate NAMESPACE and man/ files.

Documentation conventions

• Refer to R object classes with backticks: "an object of class nativeRaster"
• Don't describe internal structure that users shouldn't rely on (e.g., don't say "integer matrix organized in row-major order" for nativeRaster - users should treat it as opaque and pass to graphics functions)
• Match the style of similar existing documentation

Testing

All new functionality requires tests in tests/testthat/. See existing test files for patterns. For methods that have both a class method and standalone function form, test both interfaces and any interactions relying on field values and function parameters.

Code style

Code style is enforced by the tools described in Development practices above. In particular:

• Run lintr::lint_package() to check R code
• Space before assignment: x <- 1 not x<- 1
• The .editorconfig handles indentation and whitespace automatically in supported editors

[ctoney]

Thanks for this. I'll make use of it for a more detailed development practices, maybe breaking it out of CONTRIBUTING.md to it's own page.

The Rhub checks would be worthwhile to add also. Those are mentioned currently in CONTRUBUTING but not in any detail. For C++ code other than small and trivial, I often run the sanitizer and valgrind checks in my fork before merging. They are also run manually on main, periodically and before a release.

I ran those for #875 but in my fork after merging (https://github.com/ctoney/gdalraster/actions/runs/21268043505).