Update references to action image versions.

docs/actions-pipelines.md

@@ -60,7 +60,7 @@ Every `project.yaml` requires a `version` and an `actions` section.
 In general, actions are composed as follows:
 
 * Each action must be named using a valid YAML key (you won't go wrong with letters, numbers, and underscores) and must be unique.
-* Each action must include a `run` key which includes an officially-supported command and a version (which at present is usually just `latest`).
+* Each action must include a `run` key which includes an officially-supported command and a version. You should specify an explicit verion (do not use `latest`).
     * The `ehrql` command has the same options as described in the [ehrQL reference](ehrql/reference/cli.md#generate-dataset).
     * The `python`, `r`, and `stata-mp` commands provide a locked-down execution environment that can take one or more `inputs` which are passed to the code.
 * Each action must include an `outputs` key with at least one output, classified as either `highly_sensitive` or `moderately_sensitive`

docs/actions-scripts.md

@@ -216,14 +216,16 @@ There are two versions of the python image.  We recommend that you the use the l
 
 * `python:v2` contains Python 3.10.
   It has [this list of packages installed](https://github.com/opensafely-core/python-docker/blob/main/v2/packages.md).
-* `python:v1`, which for historical reasons is the same as `python:latest`, contains Python 3.8.
+* `python:v1` is scheduled for deprecation and should not be used. It contains Python 3.8.
   It has [this list of packages installed](https://github.com/opensafely-core/python-docker/blob/main/v1/packages.md).
 
 ### R
 
-There are two versions of the R image.  We recommend that you the use the latest verion, `r:v2`, for all R actions in your project.yaml
+There are three versions of the R image.  We recommend that you the use the latest verion, `r:v3`, for all R actions in your project.yaml
 
+* `r:v1` contains R 4.6.1.
+  It has [this list of packages installed](https://github.com/opensafely-core/r-docker/blob/main/v3/packages.md)
 * `r:v2` contains R 4.4.3.
   It has [this list of packages installed](https://github.com/opensafely-core/r-docker/blob/main/v2/packages.md)
-* `r:v1`, which for historical reasons is the same as `r:latest`, contains R 4.0.5.
+* `r:v1` is scheduled for deprecation and should not be used. It contains R 4.0.5.
   It has [this list of packages installed](https://github.com/opensafely-core/r-docker/blob/main/v1/packages.md).

docs/getting-started/how-to/troubleshoot-common-codespaces-issues/index.md

@@ -84,8 +84,8 @@ These action images are the environment in which your code is executed via the [
 
 For actions that use these image versions in their `run: ` stanza in project.yaml, we expect the behaviour of your R or python scripts to be the same when executed via `opensafely run` or directly in codespace environment (or in the provided RStudio environment for R).
 
-If you have actions defined in your [project pipeline file](../../../actions-pipelines.md#projectyaml-format) that reference older images like `python:v1` or `jupyter:v1` (or — due to an _unfortunate_ historical naming convention —  `python:latest` or `jupyter:latest`),
-or the newer `r:v2` image, then the behaviour of your code when run in those images may not be the same as if you run the code directly in the codespace. This is because the installed packages and versions of Python or R that are available differ between these environments.
+If you have actions defined in your [project pipeline file](../../../actions-pipelines.md#projectyaml-format) that reference older images like `python:v1` or `jupyter:v1`,
+or the newer `r:v2` or `r:v3` images, then the behaviour of your code when run in those images may not be the same as if you run the code directly in the codespace. This is because the installed packages and versions of Python or R that are available differ between these environments.
 
 If this is the case for your project, your options are:
 
@@ -94,7 +94,6 @@ For older images like `python:v1` or `jupyter:v1`:
 * Update your project pipeline file to reference the most recent action images and make any neccesary changes to your code (recommended)
 * Retain the references to the older action images, and use [`opensafely exec`](../../../opensafely-cli.md#exec-interactive-development) for interactive development using these action images' environments
 
-For the recently released `r:v2` image, until we have support for its version of R and libraries natively in codespaces, you can:
+For the more recently released `r:v2` and `r:v3` images, until we have support for its version of R and libraries natively in codespaces, you can:
 
-* Follow the instructions for [manually running `r:v2` instance of Rstudio in codespaces](../use-github-codespaces-in-your-project/index.md#rstudio-with-the-rv2-image) (recommended)
-* Use the older `r:v1` image in your actions, and the integrated codespaces RStudio.
+* Follow the instructions for [manually running an alternative instance of Rstudio in codespaces](../use-github-codespaces-in-your-project/index.md#rstudio-with-the-rv2-image) (recommended)

docs/getting-started/how-to/use-github-codespaces-in-your-project/index.md

@@ -147,7 +147,7 @@ The research code repository that you created already has a minimal, working Ope
 ### RStudio with the r:v1 image
 
 Our codespace environment includes RStudio based on the [`r:v1` image](../../../actions-scripts.md#r).
-If you are using the `r:v1` image in your project, you can access RSTudio via:
+If you are using the `r:v1` image in your project, you can access RStudio via:
 
 1. In Visual Studio Code,
    select the "Ports" tab
@@ -158,29 +158,29 @@ If you are using the `r:v1` image in your project, you can access RSTudio via:
 1. A new browser tab/window appears with RStudio v1 running.
 
 
-### RStudio with the r:v2 image.
+### RStudio with the r:v2 or r:v3 images.
 
-Our codespaces environment does not yet natively support the new `r:v2` image with its builtin RStudio support. We anticipate adding explicit support for `r:v2` to codespaces in the future.
+Our codespaces environment does not yet natively support the later `r:v2` or `r:v3` image with their builtin RStudio support. We anticipate adding explicit support for `r:v2` and `r:v3` to codespaces in the future.
 
-However, you can manually run a version of RStudio that uses the `r:v2` image with the following command:
+However, you can manually run a version of RStudio that uses an alternative image with the following command:
 
 ```
-opensafely launch rstudio:v2 --background
+opensafely launch rstudio:v3 --background
 ```
 
-Note: the first time you run it, it may take a while as it downloads the rstudio:v2 docker image.
+Note: the first time you run it, it may take a while as it downloads the rstudio:v3 docker image.
 
-This will start an instance of RStudio on port 8788 using the v2 image in your codespace and automatically open a browser window pointing to it.
-You should be able to edit and run your project's `r:v2` code using this instance of RStudio.
+This will start an instance of RStudio on port 8788 using the v3 image in your codespace and automatically open a browser window pointing to it.
+You should be able to edit and run your project's `r:v3` code using this instance of RStudio.
 
 You can navigate back to this RStudio instance using VSCode's "Ports" tab:
 
 1. In Visual Studio Code,
    select the "Ports" tab
    (next to "Terminal").
 1. Port 8788 should be listed —
-   this is configured by the RStudio v2 server.
+   this is configured by the RStudio v3 server.
 1. Right-click on port 8788 and select "Open in browser".
-1. A new browser tab/window appears with RStudio v2 running.
+1. A new browser tab/window appears with RStudio v3 running.
 
-When you return to your codespace after it has shut down, you will need to manually re-run the above command to start the RStudio v2 instance again.
+When you return to your codespace after it has shut down, you will need to manually re-run the above command to start the RStudio v3 instance again.

docs/getting-started/tutorial/add-a-scripted-action-to-the-pipeline/index.md

@@ -97,7 +97,7 @@ This code reads the CSV of patient data, and saves a histogram of ages to a new
             dataset: output/dataset.csv.gz
 
       generate_report:
-        run: r:v2 analysis/report.R
+        run: r:v3 analysis/report.R
         needs: [generate_dataset]
         outputs:
           moderately_sensitive:

docs/requesting-libraries.md

@@ -18,9 +18,9 @@ issue](https://github.com/opensafely-core/r-docker/issues) to request it be adde
 
 We consider the following things when deciding whether to include a new R package:
 
-* The quality of the package. The vast majority of our packages come from CRAN. In r:v2 we can install from a remote repository, for such packages the package must build and be able to be added to our [r-universe](https://opensafely-core.r-universe.dev/).
+* The quality of the package. The vast majority of our packages come from CRAN. In r:v2 and r:v3 we can install from a remote repository, for such packages the package must build and be able to be added to our [r-universe](https://opensafely-core.r-universe.dev/).
 * Is the package "in scope"? In other words does the package help to process and analyse data available within the OpenSAFELY secure environment, and is this clear from the request? If it's not clear what the package will be used for, we may ask for more information to justify its inclusion, so try to communicate this from the start.
-    * Is this a package you just require, for example, for post processing released outputs. If so, in r:v2 you can install your own local packages simply by running
+    * Is this a package you just require, for example, for post processing released outputs. If so, in r:v2/r:v3 you can install your own local packages simply by running
       ```r
       install.packages("PACKAGENAME")
       ```