From 050e485227a1525425f61d1998337f92b7d03108 Mon Sep 17 00:00:00 2001 From: Jordan Jensen <jordan.jensen@rstudio.com> Date: Thu, 16 Jan 2025 15:25:50 -0800 Subject: [PATCH] Rewrite collaboration document --- docs/collaboration.md | 99 ++++++++++++++++++++++++++++--------------- 1 file changed, 66 insertions(+), 33 deletions(-) diff --git a/docs/collaboration.md b/docs/collaboration.md index b4d334fcc..467c2a74d 100644 --- a/docs/collaboration.md +++ b/docs/collaboration.md @@ -4,63 +4,96 @@ publish content to Posit Connect using [Visual Studio Code](https://code.visualstudio.com/) and [Positron](https://positron.posit.co/)—enables seemless collaboration. This -workflow guide shows how to collaborate with others on a piece of content. +workflow guide explains how to collaborate with others on a deployed piece of +content. -## Initial setup +## Deployment and Configuration files -To ensure that others can collaborate without issue the deployment and -configuration files should be available. +Posit Publisher creates and utilizes two files for deploying content. Both are +inside of the `.posit/publish` directory in the same directory as +your entrypoint file. -That means including them in the repository for the project or including them -in the `files` attribute in the configuration so they are available in the -content bundle. +The first is the Configuration file which describes how the content will be +deployed to Posit Connect. -When Posit Publisher creates a configuration it has the deployment and -configuration files included for deployment. +An example of a Configuration file is `/.posit/publish/content-title-061E.toml`. -The inclusions are in the `files` list and look like: +The second is the Deployment file which contains details on where the content +was deployed and its state. Deployment files are automatically generated by +Posit Publisher and update during deploys. -- `/.posit/publish/deployments/deployment-58A3.toml` for the deployment file -- `/.posit/publish/content-title-061E.toml` for the configuration file +An example of a Deployment file is +`/.posit/publish/deployments/deployment-58A3.toml`. -The inclusion of the deployment and configuration files allows others to easily -collaborate when they use the Source Version content bundle as a starting point. +Utilizing both of these files, alongside a credential and collaborator access +on Posit Connect, you and your collaborators can update and configure a single +piece of content. -## As a collaborator +### Collaborator access -### Start from a repository +The original creator of a piece of content on Posit Connect needs to give others +the collaborator permissions to update the content. -Clone the repo +See the [Posit Connect User Guide - Access list settings](https://docs.posit.co/connect/user/content-settings/#set-collaborators) +documentation for more information on giving users access to update a piece of +content. -### Start from a content bundle +## Source control setup -Download the Source Version content bundle. If .posit files are included. +Deployment and Configuration files found in `./posit/publish` are intended +to be committed into source repositories. -They are included by default +Once tracked in source control, anyone with access can easily collaborate on the +same piece of content. -See the -[Posit Connect User Guide - Source Versions](https://docs.posit.co/connect/user/source-versions/) -documentation for more information on how to download the content bundle. +After a deploy be sure to commit any changes to the Deployment and Configuration +files. Keeping them in sync with the content on Posit Connect will ensure that +collaborators have the most up-to-date details to continue where others left +off. -Callout note about how this only includes deployed files. +## Content bundle setup -### First time deploying +If you and your collaborators aren't using source control, a content bundle +containing the source code and data for a piece of content can be downloaded +from Posit Connect. Content bundles are created when content is published and +they work great with Posit Publisher. -If the deployment is pointed to a server that you have not deployed to before, -you may need to setup your credentials. +When deploying, include the Deployment and Configuration files so others can +use them to collaborate after they download the content bundle. -Posit Publisher makes this easy by prompting you to _Create a new Credential_ -when the selected deployment requires a credential you don't have. +Posit Publisher includes both files automatically in configurations it generates +to make this effortless. + +See the +[Posit Connect User Guide - Source Versions](https://docs.posit.co/connect/user/source-versions/) +documentation for more information on the content bundle source versions and +how to download them. -TODO: SCREENSHOT +> [!NOTE] +> The content bundle will only contain files sent to Posit Connect. Be sure any +> files that you would like collaborators to have access to are in the +> Configuration's included `files`. +> For more details see the [Project Files documentation for Posit Publisher](./vscode.md#project-files). -## While collaborating +## Tips + +### Stay updated while collaborating While collaborating on a piece of content, stay updated with the latest changes others have made. -To do so, pull down the latest changes from the repository or download the -content bundle from the latest Source Version on Posit Conect. +To do so, either pull down the latest changes from the repository or download +the content bundle from the latest Source Version on Posit Conect. Doing so ensures that you have the most up-to-date content, but also configuration settings and deployment details. + +### First time deploying + +If a deployment is pointed to a server that you have not deployed to before, +you may need to setup your credentials. + +Posit Publisher makes this easy by prompting you to _Create a new Credential_ +when the selected deployment requires a credential you don't have. + +TODO: SCREEN SHOT