diff --git a/.Rbuildignore b/.Rbuildignore index 38899f7..c61c611 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -23,4 +23,5 @@ knitreadme.sh ^debug\.R$ ^CRAN-RELEASE$ ^cran-comments\.md$ -.envrc \ No newline at end of file +.envrc +^\.idea$ \ No newline at end of file diff --git a/.circleci/config.yml b/.circleci/config.yml index 3539194..1e19dc2 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,5 +1,5 @@ ## tic Circle CI template: linux-matrix-deploy -## revision date: 2022-08-28 +## revision date: 2026-01-21 version: 2.1 jobs: r-release: @@ -64,7 +64,7 @@ jobs: # r-devel-env environment: docker: - - image: rocker/verse:devel + - image: rocker/tidyverse steps: - checkout diff --git a/.gitignore b/.gitignore index 0c6f8c1..c783eee 100644 --- a/.gitignore +++ b/.gitignore @@ -104,4 +104,5 @@ debug.R launch.json CRAN-RELEASE +.idea .envrc \ No newline at end of file diff --git a/DESCRIPTION b/DESCRIPTION index 1559d02..c37b563 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,9 @@ Package: circle Title: R Client Package for Circle CI -Version: 0.7.3 +Version: 0.7.4 Authors@R: c( - person("Patrick", "Schratz", , "patrick.schratz@gmail.com", role = c("aut", "cre"), + person("David", "Munoz Tord", , "david.munoztord@mailbox.org", role = c("cre", "ctb")), + person("Patrick", "Schratz", , "patrick.schratz@gmail.com", role = c("aut"), comment = c(ORCID = "0000-0003-0748-6624")), person("Max", "Joseph", role = "rev", comment = "Max reviewed the package for ropensci, see "), diff --git a/NEWS.md b/NEWS.md index 1eca1c0..7183342 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,26 @@ +# circle 0.7.4 + +## Bug fixes + +- Rocker/verse:devel outdated. + +## Documentation + +- πŸ“ Clean up the tic badge link. + +## update + +- Change maintainer. + +- Add vignettes. + +## Uncategorized + +- Bump actions/checkout from 4 to 5 + + # circle 0.7.3 - Account for deprecated `usethis` functions diff --git a/cran-comments.md b/cran-comments.md index dcd5e72..133d71d 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,23 +1,22 @@ -circle 0.7.3 +circle 0.7.4 -## Cran Repository Policy - -- [x] Reviewed CRP last edited 2024-04-04. - -See changes at https://github.com/eddelbuettel/crp/compare/master@%7B2022-07-26%7D...master@%7B2024-04-04%7D ## R CMD check results -- [x] Checked locally, R 4.4.1 -- [x] Checked on CI system, R 4.4.1 +- [x] Checked locally, R 4.5.0 +- [x] Checked on CI system, R 4.5.0 - [x] Checked on win-builder, R devel Check the boxes above after successful execution and remove this line. Then run `fledge::release()`. ## Current CRAN check results -- [x] Checked on 2024-07-31, problems found: https://cran.r-project.org/web/checks/check_results_circle.html -- [x] WARN: r-devel-linux-x86_64-debian-clang, r-devel-linux-x86_64-debian-gcc, r-devel-linux-x86_64-fedora-clang, r-devel-linux-x86_64-fedora-gcc, r-devel-windows-x86_64 - Missing or unexported object: β€˜usethis::github_token’ +- [x] Checked on 2026-01-21, problems found: https://cran.r-project.org/web/checks/check_results_circle.html +- [x] Note: r-devel-linux-x86_64-debian-clang, r-devel-linux-x86_64-debian-gcc, r-devel-linux-x86_64-fedora-clang, r-devel-linux-x86_64-fedora-gcc, r-devel-windows-x86_64 + +New maintainer: + David Munoz Tord +Old maintainer(s): + Patrick Schratz Check results at: https://cran.r-project.org/web/checks/check_results_circle.html diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 36e47a3..f728a0f 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -33,3 +33,13 @@ reference: contents: - circle-package - list_projects +articles: + - title: Getting started + contents: + - circle + - title: Advanced usage + contents: + - advanced + - title: CI with tic + contents: + - tic diff --git a/tic.R b/tic.R index d8d30e3..70fcc5c 100644 --- a/tic.R +++ b/tic.R @@ -1,4 +1,9 @@ -do_package_checks(codecov = FALSE) +do_package_checks( + codecov = FALSE, + args = c("--as-cran", "--no-manual"), + build_args = "--force", + error_on = "warning" +) if (ci_on_circle()) { get_stage("before_deploy") %>% diff --git a/vignettes/advanced.Rmd b/vignettes/advanced.Rmd new file mode 100644 index 0000000..488e603 --- /dev/null +++ b/vignettes/advanced.Rmd @@ -0,0 +1,121 @@ +--- +title: "Advanced usage and {tic} integration" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Advanced usage and {tic} integration} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + eval = !identical(Sys.getenv("CI"), "true") && !identical(Sys.getenv("CRAN"), "true") +) +``` + +# Overview + +This vignette covers advanced workflows with {circle} and how to integrate them with {tic}. +It assumes you have completed the basics in the "Getting Started" vignette. + +# Advanced API usage + +## Pipelines, workflows, and jobs + +Use the high-level helpers to browse recent activity and drill down into details. + +```r +# list recent pipelines for a repo +circle::get_pipelines(owner = "ropensci", repo = "circle") + +# list workflows of a given pipeline id +# (replace with a pipeline id from the previous result) +circle::get_workflows(pipeline_id = "") + +# list jobs of a workflow +circle::get_jobs(workflow_id = "") +``` + +## Restarting and retrying + +```r +# trigger a new build (pipeline) for a branch +circle::new_build(branch = "main") + +# retry a workflow (if supported by the API) +circle::retry_workflow(workflow_id = "") +``` + +## Artifacts and logs + +```r +# list and download build artifacts +arts <- circle::get_build_artifacts(job_number = 123) +arts +``` + +## Environment variables + +```r +# read and set environment variables in a project context +circle::get_env_vars(owner = "ropensci", repo = "circle") +circle::set_env_var(owner = "ropensci", repo = "circle", name = "MY_TOKEN", value = "***") +``` + +# Deep integration with {tic} + +The [{tic}](https://docs.ropensci.org/tic/) package provides a CI-agnostic DSL and ready-made +templates for CircleCI. Combine {circle} (API client) with {tic} (workflow setup) to automate +checks and deployments. + +## Initialize CircleCI with {tic} + +```r +# writes .circleci/config.yml and a tic.R with sensible defaults +tic::use_circle_yml() + +# or go through the interactive wizard +tic::use_tic() +``` + +## Customize stages + +Edit `tic.R` to add or modify stages. For example, enable pkgdown deployment only on tags: + +```r +if (ci_has_env("BUILD_PKGDOWN") && tic::on_tag()) { + get_stage("deploy") %>>% { + tic::step_do_call("pkgdown::build_site") + tic::step_do_call("tic::do_pkgdown") + } +} +``` + +## Authentication and permissions + +For deployments, set up a user key once using {circle}: + +```r +circle::use_circle_deploy() +``` + +This adds a user key on CircleCI and registers the corresponding key in your GitHub account, +so that `tic::deploy()` can push the pkgdown site to `gh-pages`. + +## Making vignettes robust on CI/CRAN + +Ensure vignettes build in non-interactive environments by guarding heavy code (already enabled +at the top of this vignette): + +```r +knitr::opts_chunk$set( + eval = !identical(Sys.getenv("CI"), "true") && !identical(Sys.getenv("CRAN"), "true") +) +``` + +# See also + +- Getting Started (introductory guide) +- Using {circle} with {tic} (step-by-step setup walkthrough) diff --git a/vignettes/circle.Rmd b/vignettes/circle.Rmd index c6cf010..0b19623 100644 --- a/vignettes/circle.Rmd +++ b/vignettes/circle.Rmd @@ -2,7 +2,7 @@ title: "Getting Started" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{circle} + %\VignetteIndexEntry{Getting Started} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -10,7 +10,8 @@ vignette: > ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, - comment = "#>" + comment = "#>", + eval = !identical(Sys.getenv("CI"), "true") && !identical(Sys.getenv("CRAN"), "true") ) ``` @@ -50,10 +51,13 @@ By querying information about the user and enabling a project one can check if e `get_circle_user()` makes uses of the Circle CI API key. - -```r +```{r, eval=FALSE} circle::get_circle_user() +``` + +Example output: +``` $content $content$name [1] "Patrick Schratz" @@ -64,27 +68,24 @@ $content$login $content$id [1] "9c373331-d0f7-45e1-afe6-4a5c75e00d10" - $path [1] "/me" $response -Response [https://circleci.com/api/v2/me?circle-token=39d697f345d8d8a92ab07c333405d9b0092d116c] +Response [https://circleci.com/api/v2/me?circle-token=***] Date: 2021-01-07 20:07 Status: 200 Content-Type: application/json;charset=utf-8 Size: 86 B - attr(,"class") [1] "circle_user" ``` `enable_repo()` also uses the GitHub token. -```r -circe::enable_repo() -βœ” Successfully enabled repo 'ropensci/circle' on Circle CI. +```{r, eval=FALSE} +circle::enable_repo() ``` After the repo has been enabled, it should be returned in `circle::list_projects()`. @@ -96,10 +97,14 @@ Configuring build deployments can be a bit tedious with respect to permissions. Here `circle::use_circle_deploy()` helps as it creates a SSH key pair which will enable deployment. The private key will be stored in GitHub (under "Settings -> SSH and GPG keys") and the public key on Circle CI (on the respective project page in "SSH Keys"). -```r +```{r, eval=FALSE} circle::use_circle_deploy() +``` + +Example output: + +``` βœ– No 'user-key' found. -────────────────────────────────────────────────────────────────────────────────────────────────── βœ” Added a 'user key' to project '' on Circle CI. This enables deployment from builds. ``` @@ -131,14 +136,14 @@ To enable deployment to a repository however, a "user-key" is needed. This key type also has "write" permissions and can be added using `use_circle_deploy()`. `use_circle_deploy()` will add a so called "user key" to the settings of the repo on Circle CI. The private key will be added to your GitHub profile under the "SSH and GPG keys" section with the title pointing to the respective repo. -See also [the Circle CI section about deployment](https://circleci.com/docs/deployment-integrations/). +See also [the Circle CI section about deployment](https://circleci.com/docs/guides/deploy/deployment-overview//). (If for some reasons you do not want to use `use_circle_deploy()` and go the manual way of adding a SSH key to Circle CI, please be aware of [this issue](https://discuss.circleci.com/t/adding-ssh-keys-fails/7747).) # Starting a Build As with almost every CI provider, a YAML configuration files is required to specify the tasks that should be executed during a build. -Currently Circle CI does not come with official support for the R language but you can add [your vote here](https://ideas.circleci.com/images/p/add-official-support-for-r). +Currently Circle CI does not come with official support for the R language but you can add [your vote here](https://ideas.circleci.com/cloud-feature-requests/p/add-official-support-for-r). Since Circle CI is heavily based on docker this is not really a problem. One can simply use the [rocker](https://github.com/rocker-org/rocker) R images to have first-class support with respect to R containers. Official support for R would mean that the images are cached on Circle CIs side and be directly available on build start. @@ -147,3 +152,8 @@ Currently, `rocker` images need to be downloaded in every build again. {circle} does not come with a template for running R builds as it focuses on API and build metadata functionality. Instead, have a look at [ropensci/tic](https://docs.ropensci.org/tic/) and its functions `tic::use_tic()` and `tic::use_circle_yml()` to quickly get R builds running on Circle CI. Alternatively you can borrow the config that is being used [in this repo](https://github.com/ropensci/circle/blob/main/.circleci/config.yml) - which was also created via {tic}. + +# See also + +- Using {circle} with {tic}: https://docs.ropensci.org/circle/articles/tic.html +- Advanced usage and {tic} integration: https://docs.ropensci.org/circle/articles/advanced.html diff --git a/vignettes/tic.Rmd b/vignettes/tic.Rmd index d3b8349..32a32ea 100644 --- a/vignettes/tic.Rmd +++ b/vignettes/tic.Rmd @@ -2,7 +2,7 @@ title: "Using {circle} with {tic}" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{tic} + %\VignetteIndexEntry{Using {circle} with {tic}} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -10,19 +10,18 @@ vignette: > ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, - comment = "#>" + comment = "#>", + eval = !identical(Sys.getenv("CI"), "true") && !identical(Sys.getenv("CRAN"), "true") ) ``` This vignette explains how {circle} can be used in conjunction with {tic} to set up a working CI environment to check an R package and build a pkgdown site. -All following points assume you are in the project root of the R package. +Prerequisites: Please read the Getting Started vignette first for setup, authentication, and basic workflows: -## Enabling the repository on Circle CI +- Getting Started: https://docs.ropensci.org/circle/articles/circle.html -The first step is to enable/register your repository on Circle CI. -To do this, `enable_repo()` can be called. -Assuming you already have an account on Circle CI (authenticating with GitHub is recommended), this "follows" your repository on Circle CI so that builds can be triggered by pushes to the repository. +All following points assume you are in the project root of the R package and have already enabled your repository on CircleCI and configured credentials as described in Getting Started. ## Creating the Circle CI YAML configuration file