Skip to content

Commit ac7fe4d

Browse files
authored
Merge pull request #2507 from posit-dev/dotnomad/collab-doc
Add collaboration workflow document
2 parents ef117a5 + 26ea67e commit ac7fe4d

File tree

3 files changed

+81
-0
lines changed

3 files changed

+81
-0
lines changed

docs/collaboration.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Collaborative Publishing with Posit Publisher
2+
3+
This workflow guide explains how to collaborate with others on deployed content.
4+
5+
## Configuration and Deployment files
6+
7+
Posit Publisher creates two `.toml` files for deploying content.
8+
Both are in the `.posit/publish` directory, found alongside your entrypoint
9+
file.
10+
11+
- The Configuration file describes how the content will be deployed to Posit
12+
Connect. It can be edited by hand and by interacting with the Posit
13+
Publisher sidebar. It is named using the content's title and a unique
14+
identifier, for example, `content-title-061E.toml`. See the
15+
[Configuration file reference](./configuration.md) for a full list of
16+
settings.
17+
- The Deployment file details where the content was deployed and its state.
18+
Deployment files are automatically generated by Posit Publisher in the
19+
`deployment` directory and updated during deploys. They are not meant to be
20+
edited. Posit Publisher will take care of this file for you so you do not need
21+
to think about it aside from the collaboration tips below.
22+
23+
Utilizing both of these files you and your collaborators can update and
24+
configure the same content. To grant others collaborator access to content see
25+
[Posit Connect User Guide - Access list settings](https://docs.posit.co/connect/user/content-settings/#set-collaborators).
26+
27+
## With source control
28+
29+
Configuration and Deployment files found in `./posit/publish` are intended
30+
to be committed into source repositories.
31+
32+
Once tracked in source control, anyone with access can easily collaborate on the
33+
same content.
34+
35+
After a deploy, be sure to commit any changes to the Configuration and
36+
Deployment files. Keeping them in sync with the content on Posit Connect ensures
37+
that collaborators have the most up-to-date details to continue where others
38+
left off.
39+
40+
## Without source control
41+
42+
Include the Deployment and Configuration files in your deployment and others can
43+
use them to collaborate by downloading the files from Posit Connect. Posit
44+
Publisher includes both files by default.
45+
46+
Whenever content is deployed to Posit Connect, a content bundle is created
47+
containing the files. Ensure files you would like collaborators to have access
48+
to are in the [Configuration's Project `files`](./vscode.md#project-files).
49+
50+
See
51+
[Posit Connect User Guide - Source Versions](https://docs.posit.co/connect/user/source-versions/)
52+
for more information on the content bundle source versions and
53+
how to download them.
54+
55+
## Tips
56+
57+
### Stay updated while collaborating
58+
59+
Depending on whether or not you're using source control, make sure to either
60+
pull down the latest changes from source control or download the
61+
content bundle from the latest Source Version on Posit Connect before deploying.
62+
This ensures that you have the most up-to-date content, configuration settings,
63+
and deployment details.

docs/vscode.md

+10
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,16 @@ To remove a credential, right-click on it and select `Delete`.
205205
For instructions on how to create a Connect API key, see the
206206
[Connect documentation](https://docs.posit.co/connect/user/api-keys/index.html#api-keys-creating).
207207

208+
#### First time deploying
209+
210+
If a deployment is pointed to a server that you have not deployed to before,
211+
you may need to set up a credential.
212+
213+
Posit Publisher makes this easy by prompting you to **Create a new Credential**
214+
when the selected deployment requires a credential you don't have.
215+
216+
TODO: SCREEN SHOT
217+
208218
#### via dotfile
209219

210220
If your OS does not have a keychain the extension will manage your credentials

extensions/vscode/README.md

+8
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,14 @@ See the
6969
[Updating Previously Deployed Content](https://github.com/posit-dev/publisher/blob/main/docs/vscode.md#updating-previously-deployed-content)
7070
documentation for more information.
7171

72+
### Seamless collaboration
73+
74+
Collaborate with your team using shared configurations and deployments. Easily
75+
pick up where others left off with deployed content.
76+
77+
See [Collaborative Publishing with Posit Publisher](https://github.com/posit-dev/publisher/blob/main/docs/collaboration.md)
78+
for more information.
79+
7280
### Multiple deployments and configurations
7381

7482
Does your content need to be deployed to multiple destinations with different

0 commit comments

Comments
 (0)