miraisolutions / techguides

Technical guidelines around R programming

techguides

techguides is an open source project to collect technical guidelines and best practices. At Mirai Solutions we envision techguides as a dynamic and evolving project where we can share with the community some of the experience we gather in our daily work.

The current version of techguides, a bookdown website served via GitHub Pages, can be browsed at https://mirai-solutions.ch/techguides.

techguides's Issues

Possible typo in 1.4.3 : division or multiplication?

techguides/roxygen-guidelines/roxygenExPkg/R/divide_rdname.R

Lines 28 to 30 in 5f0ffe4

	divide_by <- function(x, d) {
	x * d
	}

Should this operator be a /?

Fix missing alt text

We currently ignore missing img alt text when using HTMLProofer, due to a former issue that is probably resolved by now: see #13 (comment)

Meaningful alt texts should included and the --empty-alt-ignore removed from the Actions WF

Fix broken rocker-project links

Some rocker-project links don't exist anymore and the htmlproofer step in the CI / CD fails.

To investigate updates on rocker-project in general to see how to best resolve this.

Action WF refinements

• switch to ruby/setup-ruby
  • this is now the starter workflow for Ruby, making actions/setup-ruby deprecated (see actions/setup-ruby#80)..
  • Consider bundler setup to leverage the (proper) caching are implicitly provided

As an alternative, use a containerized HTMLProofer (Docker has out-of-the-box support in Actions)

• https://github.com/gjtorikian/html-proofer#using-through-docker

Cleanup renv exclusion

We should not need to explicitly exclude the renv directory when deploying via rsconnect

techguides/shiny-ci-cd/deploy/deploy-shinyapps.R

Lines 10 to 11 in aa4edf5

	# exclude hidden files and renv directory (if present)
	appFiles = setdiff(list.files(), "renv")

This was introduced in riccardoporreca/ShinyCICD@6afa989 and implicitly also excludes .Rprofile.

This is not necessary with recent versions of rsconnect via rstudio/rsconnect#367 and rstudio/rsconnect#462

Simplification to be first tried in https://github.com/miraisolutions/ShinyCICD

Explicit book_filename and git-ignored .rds

The file _main.rds was also changed. I did not commit that yet as it seems to be automatically generated by bookdown.
It looks like we should delete this file from version control and put it into .gitignore. What is your opinion on this @riccardoporreca ?

Indeed @Chargothrond, this was committed not so long ago in 4389743, I believe accidentally. The behavior is referred to in rstudio/bookdown#430, and I agree we should git-ignore it, probably after defining an explicit book_filename in _bookdown.yml. Will create a separate Issue / PR.

Originally posted by @riccardoporreca in #20 (comment)

Customize the rendered book

The techguides don't have any Mirai specific styling yet and some other details can be improved as well:

• Quite a few entries in the table of contents on the left hand side are shortened with "..." due to their length.

GitHub repo link

In relation to the useR!2021 submission / presentation as open source project, we may also want to link back to the repository in the generated bookdown.
This should be just a matter of configuration, creating a GH icon at the top-right alongside the "social" links (to be possibly reviewed as well).

Review shiny / CI CD / renv / private dependencies

While #14 put github actions in the foreground instead of travis CI, there is still some further restructuring to consider:

• The shiny CI CD chapter has grown and it makes sense to try to split different topics better.
• The part about renv could be extended, leveraging on what we did in the Covid19 app and what was discussed / described in #17
• The information about the private / non-CRAN dependencies can also be formulated more clearly which will take care of #18 apart from the Docker component.
  • Open question: Should we consider to include information about Docker in the context of private repos for shiny apps?

Review Shiny CI/CD

https://mirai-solutions.ch/techguides/cicd-pipelines-for-automatic-deployment-of-a-r-shiny-web-app.html does not reflect the current reality: the content was written when Travis was the well-established tool and Actions was the not-yet-mature one, which is not quite the current situation.

A review is needed to have the primary focus on Actions.

Location of option() statement when using {renv}.

techguides/renv.Rmd

Lines 52 to 74 in 5f0ffe4

	### Control packages version
	As a note, if the `DESCRIPTION` file does not request a specific package version, the `renv` initialization will pick the version currently available in the user library when the snapshot of the packages was created. However, it is advisable to have a stricter control over the version of the packages used in a project. To do so, one can set the option to install dependencies from a specific MRAN repo, therefore fixing the version for all available packages.
	```{r , echo = TRUE, eval = FALSE}
	# Install all dependencies from a specific MRAN date repo
	options(repos = "https://mran.microsoft.com/snapshot/2020-11-15")
	```
	One can then install the dependencies of a package via:
	```{r , echo = TRUE, eval = FALSE}
	renv::install("remotes")
	(deps <- remotes::dev_package_deps(dependencies = TRUE))
	renv::install(with(deps, sprintf("%s@%s", package[diff!=0], available[diff!=0])))
	```
	To create a snapshot of the package dependencies and update the `renv.lock` file:
	```{r , echo = TRUE, eval = FALSE}
	# Create a snapshot to track dependencies in the lockfile
	renv::snapshot()
	```

That is a great suggestion! On the other hand, where do you put the option() statement? Are you using a project-level .Rprofile file tracked on GitHub?

Update docker-based version-stable R

The techguides content about docker and docker-based version-stable R development using Rocker is obsolete and should be updated

Switch CI-CD to rely on built-in actions/deploy-pages

• Mainly inspired by https://github.com/actions/starter-workflows/tree/main/pages
• The new setup also uploads an artifact with the built website, which is useful to asses issues

Note that this new approach to deployment requires changing the Pages settings to rely on Actions workflows at https://github.com/miraisolutions/techguides/settings/pages

---

With this, there is no need to rely on JamesIves/github-pages-deploy-action, as originally intended:

This is a more common actions used e.g. in r-lib/actions/examples

See existing TODO in the code

techguides/.github/workflows/site.yaml

Lines 57 to 61 in 16dfe2d

	# TODO: consider switching to JamesIves/github-pages-deploy-action
	# uses: JamesIves/[email protected]
	# with:
	# branch: gh-pages
	# folder: _book

private non-CRAN dependencies for Shiny app (w/ {renv} + Docker)

techguides/shiny-ci-cd.Rmd

Line 234 in 5f0ffe4

### non-CRAN dependencies

I am very interested in this section. Have you developed some best-practices or recommendations regarding how to include private non-CRAN dependencies too (especially on projects/apps/pkgs using both {renv} and Docker)?

Review Shiny CI-CD based on current Actions status

A follow-up of #14 given how GH Actions have matured, given the introduction of composite Actions and a number of convenient actions now available in https://github.com/r-lib/actions and already integrated and tested in our example app miraisolutions/ShinyCICD#6

Renv and rsconnect updates

There few new things to update in the technical guide.

https://rstudio.github.io/renv/news/index.html

• renv::init() now uses Posit Public Package Manager by default
• snapshot.type = "explicit" is not sufficient anymore, because Suggests packages must be in renv lock
• renv::install()call required to install development packages if the project is "explicit"
• settings.dcf is not created anymore, there is a json file
• New renv::checkout() installing the latest-available packages from a repository. For example, renv::checkout(date = "2023-02-08") will install the packages available on 2023-02-08 from the Posit Package Manager repository. 3.2.1 of tech guides to be updated
• Handling of development dependencies has been refined. renv::snapshot() and renv::status() no longer track development dependencies. To check if something must be written
• mention renv::dependencies()? check if worth
• Deployment with rsconnect, changed from rsconnect 1.0.2. rsconnect must be part of the renv project (init "implicit").
• rsconnect::writeManifest() required for Posit Connect

Something more:

• mran is retired (3.2.1)

renv::install("remotes")
(deps <- remotes::dev_package_deps(dependencies = TRUE))
renv::install(with(deps, sprintf("%s@%s", package[diff!=0], available[diff!=0])))

Installs all latest packages, there can be issues with new releases of renv and rsconnect

4.2.1.3 Deployment
options(rsconnect.pkrat = FALSE) or TRUE depending if deployment should happen with renv