cran check

Author: beabock

.Rbuildignore

@@ -5,4 +5,5 @@
 ^LICENSE\.md$
 ^CITATION\.cff$
 ^RELEASING\.md$
+^cran-comments\.md$
 ^emissions\.csv$

CITATION.cff

@@ -8,8 +8,8 @@ authors:
 type: software
 license: MIT
 repository-code: "https://github.com/beabock/CodeCarbonR"
-version: 0.0.0.9000
-date-released: "2026-08-04"
+version: 0.1.0
+date-released: "2026-08-19"
 # Once tagged and archived on Zenodo, add the minted DOI here, e.g.:
 # doi: 10.5281/zenodo.XXXXXXX
 # and Zenodo's concept DOI (the one that always resolves to the latest

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: CodeCarbonR
 Title: Track Energy Consumption and Carbon Emissions of R Code
-Version: 0.0.0.9000
+Version: 0.1.0
 Authors@R:
-    person("Beatrice", "Bock", email = "beabockm@gmail.com", role = c("aut", "cre"))
+    person("Beatrice", "Bock", email = "beabockm@gmail.com", role = c("aut", "cre", "cph"))
 Description: Wraps the Python 'codecarbon' package via 'reticulate' to
     measure the energy consumption and estimated carbon emissions of R
     code. Provides a self-contained setup routine that installs

NEWS.md

@@ -1,4 +1,4 @@
-# CodeCarbonR 0.0.0.9000
+# CodeCarbonR 0.1.0
 
 ## New features
 

R/countries.R

@@ -5,6 +5,15 @@
 #' [with_emissions_tracked()] must be one of the codes returned here.
 #'
 #' @return A data frame with `iso_code` and `country_name` columns.
+#' @examples
+#' \donttest{
+#' # Requires codecarbon to be installed (setup_carbon_tracker()); not run
+#' # on CRAN's check machines, which don't have it.
+#' if (carbon_tracker_ready()) {
+#'   countries <- list_carbon_tracker_countries()
+#'   head(countries)
+#' }
+#' }
 #' @export
 list_carbon_tracker_countries <- function() {
   ensure_codecarbon_available()

R/setup.R

@@ -21,6 +21,13 @@
 #' @param force Reinstall codecarbon even if it's already available.
 #' @return Invisibly, `TRUE` if codecarbon is ready to use after the call,
 #'   `FALSE` if setup was cancelled.
+#' @examples
+#' \dontrun{
+#' # Installs software and prompts for confirmation, so this never runs
+#' # under R CMD check (or any other non-interactive session) -- call it
+#' # once, by hand, from an interactive R console.
+#' setup_carbon_tracker()
+#' }
 #' @export
 setup_carbon_tracker <- function(force = FALSE) {
   if (!force && carbon_tracker_ready()) {
@@ -68,6 +75,8 @@ setup_carbon_tracker <- function(force = FALSE) {
 #'
 #' @return `TRUE` if codecarbon can be imported, `FALSE` otherwise (including
 #'   when no Python interpreter can be found at all).
+#' @examples
+#' carbon_tracker_ready()
 #' @export
 carbon_tracker_ready <- function() {
   tryCatch(reticulate::py_module_available("codecarbon"), error = function(e) FALSE)

R/tracker.R

@@ -67,6 +67,18 @@ CarbonTracker <- R6::R6Class(
 #' @param ... Passed to `codecarbon.OfflineEmissionsTracker`, e.g.
 #'   `measure_power_secs`, `output_dir`, `log_level`.
 #' @return A `CarbonTracker` R6 object.
+#' @examples
+#' \donttest{
+#' # Requires codecarbon to be installed (setup_carbon_tracker()); not run
+#' # on CRAN's check machines, which don't have it.
+#' if (carbon_tracker_ready()) {
+#'   tracker <- carbon_tracker(country_iso_code = "USA", output_dir = tempdir())
+#'   tracker$start()
+#'   Sys.sleep(1)
+#'   emissions <- tracker$stop()
+#'   print(emissions)
+#' }
+#' }
 #' @export
 carbon_tracker <- function(country_iso_code = NULL, project_name = "CodeCarbonR", ...) {
   CarbonTracker$new(country_iso_code = country_iso_code, project_name = project_name, ...)

R/with-emissions-tracked.R

@@ -7,6 +7,19 @@
 #' @param ... Passed to [carbon_tracker()].
 #' @return A `carbon_emissions_result`: `$result` holds the value of `expr`,
 #'   `$emissions` holds the `carbon_emissions` object.
+#' @examples
+#' \donttest{
+#' # Requires codecarbon to be installed (setup_carbon_tracker()); not run
+#' # on CRAN's check machines, which don't have it.
+#' if (carbon_tracker_ready()) {
+#'   out <- with_emissions_tracked(
+#'     Sys.sleep(1),
+#'     country_iso_code = "USA",
+#'     output_dir = tempdir()
+#'   )
+#'   print(out)
+#' }
+#' }
 #' @export
 with_emissions_tracked <- function(expr, country_iso_code = NULL, ...) {
   tracker <- carbon_tracker(country_iso_code = country_iso_code, ...)

RELEASING.md

@@ -124,3 +124,69 @@ guarantees on top. Frictions specific to this package:
   explaining that `codecarbon` has no R equivalent and that setup is
   opt-in, confirmed, and isolated to its own conda environment rather
   than touching the user's system Python.
+
+### 4a. Step-by-step, once you decide to go for it
+
+Pre-submission (in addition to the package-specific fixes above):
+
+- [ ] Every exported function (`setup_carbon_tracker()`, `carbon_tracker()`,
+      `with_emissions_tracked()`, `list_carbon_tracker_countries()`,
+      `carbon_tracker_ready()`) needs an `@examples` block in its roxygen
+      comment. None currently exist. Wrap any example that would call
+      `setup_carbon_tracker()`, start a tracker, or otherwise touch
+      Python/network in `\donttest{}` (runs on your machine, skipped on
+      CRAN's checks) -- e.g. show `list_carbon_tracker_countries()` or
+      `carbon_tracker_ready()` unwrapped since those don't touch Python,
+      but wrap a `with_emissions_tracked()` example in `\donttest{}`.
+- [ ] Confirm `Authors@R` includes a copyright holder role -- add `"cph"`
+      to Beatrice Bock's `role = c(...)` in `DESCRIPTION` if it's only
+      `c("aut", "cre")` currently (CRAN wants an explicit copyright holder,
+      not just author/maintainer).
+- [ ] Write `cran-comments.md` at the repo root (`.Rbuildignore` it if you
+      don't want it in the built tarball, though CRAN's web form also asks
+      for these comments directly). Cover: this is a first submission;
+      what the package does in one line; and the Python/conda point noted
+      above -- `codecarbon` has no R equivalent, `setup_carbon_tracker()`
+      is opt-in/interactive/confirmed and installs into its own isolated
+      conda environment, never touches the user's system Python, and
+      never runs during `R CMD check` (it errors intentionally in
+      non-interactive contexts, which is what the test suite checks for).
+- [ ] From R, in the package directory:
+      ```r
+      usethis::use_version("minor")   # bumps 0.0.0.9000 -> 0.1.0, tags NEWS.md
+      devtools::check(remote = TRUE, manual = TRUE)   # full local check
+      devtools::check_win_devel()      # builds on R's Windows dev servers, emails you the log
+      urlchecker::url_check()          # catches dead links in docs/README/vignette
+      ```
+      All three should come back clean (0 errors, 0 warnings, ideally 0
+      notes) before submitting. `check_win_devel()` in particular catches
+      things your local machine's R version won't.
+- [ ] Update `NEWS.md`'s heading from `# CodeCarbonR (development version)`
+      (or `0.0.0.9000`) to the real version, and `CITATION.cff`'s
+      `version:`/`date-released:` to match.
+
+Submission:
+
+- [ ] `devtools::submit_cran()` -- builds the source tarball, uploads it
+      to CRAN's submission form, and pulls maintainer info + your
+      `cran-comments.md` content into the form automatically. (Manual
+      alternative: build with `R CMD build .`, then upload the resulting
+      `.tar.gz` yourself at
+      [cran.r-project.org/submit.html](https://cran.r-project.org/submit.html).)
+- [ ] **(you)** CRAN emails a confirmation link to the maintainer address
+      in `DESCRIPTION` -- click it. The submission doesn't enter the queue
+      until confirmed.
+- [ ] Wait. CRAN's automated checks (multiple OSes/R versions) typically
+      report back within a day or two; a human CRAN team member reviews
+      after that. Total time is unpredictable -- same-day acceptances and
+      multi-week back-and-forth both happen, and a package installing
+      external software during setup (even opt-in) is exactly the kind of
+      thing that can prompt a question rather than an immediate accept.
+- [ ] If CRAN comes back with required changes: fix them, bump the patch
+      version again (e.g. `0.1.0` -> `0.1.1`), add a line to
+      `cran-comments.md` under a "Resubmission" heading explaining what
+      changed, and resubmit the same way.
+- [ ] On acceptance: tag/release on GitHub if you haven't already (Section
+      2 above), then bump `DESCRIPTION`'s version to a new `.9000`
+      development suffix (e.g. `0.1.0.9000`) so it's clear `main` is past
+      the released version.

cran-comments.md

@@ -0,0 +1,43 @@
+# CRAN comments
+
+## Submission
+
+This is the first submission of CodeCarbonR to CRAN.
+
+CodeCarbonR wraps the Python `codecarbon` package (via `reticulate`) to
+measure the energy consumption and estimated carbon emissions of R code.
+There is no R-native equivalent of `codecarbon`, which is why this package
+depends on a Python backend rather than reimplementing emissions tracking
+natively.
+
+## Notes on Python/conda dependency
+
+* `setup_carbon_tracker()` is the only function that installs software. It
+  is opt-in (never called automatically), requires explicit user
+  confirmation via `utils::menu()`, and installs `codecarbon` into its own
+  dedicated conda environment (`r-codecarbon`) rather than touching the
+  user's system Python or any existing R/Python installation.
+* `setup_carbon_tracker()` refuses to run in a non-interactive session
+  (`stop()`s immediately if `!interactive()`), so it never runs during
+  `R CMD check`, and this refusal is itself covered by a test
+  (`tests/testthat/test-setup.R`).
+* No example, test, or vignette installs software, writes outside
+  `tempdir()`, or requires network access during `R CMD check`.
+  Examples and tests that would otherwise touch Python/codecarbon are
+  wrapped in `\donttest{}`/`\dontrun{}` or guarded with
+  `testthat::skip_on_cran()` plus a runtime `carbon_tracker_ready()`
+  check, so they no-op cleanly on CRAN's check machines (which will not
+  have codecarbon installed).
+* `vignettes/quickstart.Rmd` uses `eval = FALSE` on every chunk and shows
+  realistic example output as literal text, so building it never touches
+  Python or the network.
+
+## R CMD check results
+
+0 errors | 0 warnings | 0 notes (checked with `R CMD check --as-cran` on
+Windows; see `RELEASING.md` for details of this package's release
+process).
+
+## Downstream dependencies
+
+This is a new package; there are no reverse dependencies.