troubleshooting renv

docs/troubleshooting.md

@@ -50,6 +50,28 @@ For example, in [Posit Connect 2024.12.0](https://docs.posit.co/connect/news/#po
 Gradio app support was introduced. When deploying a Gradio app to a server
 running an older version of Posit Connect than 2024.12.0, it will error.
 
+### `renv` errors on deployment
+
+When deploying projects using `R`, it is indispensable for the Posit Publisher extension
+to have access to a record of the dependencies used by your project.
+This record is expected to be found as a `lockfile` (commonly named as `renv.lock`) generated by `renv`,
+since the [`renv` package](https://rstudio.github.io/renv/articles/renv.html)
+is a great choice to create reproducible environments.
+
+Clarifying things a bit, `renv` is not a requirement, the `lockfile` is.
+It is possible to collaborate in projects that already have a `lockfile`
+and not having `renv` available in your system.
+
+If there is not a `lockfile`, the Posit Publisher extension will attempt to scan the current state of the project
+and provide you with a solution to generate the expected `lockfile`.
+
+![](https://cdn.posit.co/publisher/assets/img/publisher-renv-setup-notification.png)
+
+Solutions provided by the Posit Publisher extension to fix an `renv` environment are limited
+to the most common scenarios, any other issue around `renv` and a `lockfile` generation will require
+additional attention by you. For those cases the Posit Publisher extension will suggest
+to evaluate the situation getting the status of the environment with `renv::status()`.
+
 ## Still having trouble?
 
 If you're still having trouble with Posit Publisher or have any questions,