Skip to content

Commit 6fb44e3

Browse files
dotNomaddotNomad
authored
Add Gallery documentation to the contributing guide (#47)
* Add README link to the contributing doc * Remove template connect-extension.toml * Add initial draft of gallery contributing guide * Add a doc with a template for custom workflows
1 parent b11beb5 commit 6fb44e3

File tree

6 files changed

+329
-8
lines changed

6 files changed

+329
-8
lines changed

‎.github/workflows/extensions.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,8 @@ jobs:
100100
# workflow
101101
publisher-command-center:
102102
needs: [complex-extension-changes]
103+
# Only runs if the `complex-extension-changes` job detects changes in the
104+
# publisher-command-center extension directory
103105
if: ${{ needs.complex-extension-changes.outputs.publisher-command-center == 'true' }}
104106
uses: ./.github/workflows/publisher-command-center.yml
105107

@@ -112,6 +114,8 @@ jobs:
112114
# If no releases were triggered the output for releases will be `[]`
113115
fetch-releases:
114116
runs-on: ubuntu-latest
117+
# Requires that the `simple-extensions` and all custom workflow jobs are
118+
# completed before running this job
115119
needs: [simple-extensions, publisher-command-center]
116120
if: ${{ always() }}
117121
outputs:

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
11
# connect-extensions
22

33
Home for connect extensions
4+
5+
### Adding Content
6+
7+
See the [contributing guide](https://posit-dev.github.io/connect-extensions/contributing.html)
8+
to learn how to contribute content, and add it to the Connect Gallery.

‎_quarto.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ project:
22
type: website
33
render:
44
- "extensions/**/connect-extension.qmd"
5+
- docs/*.qmd
56
- contributing.qmd
67
- extensions.qmd
78
- index.qmd

‎_template/connect-extension.toml‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎contributing.qmd‎

Lines changed: 236 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,242 @@ A file that has the name of your extension, the categories it falls into, and a
2222
{{< include _template/connect-extension.qmd >}}
2323
```
2424

25-
### `connect-extension.toml`
25+
# Connect Gallery
2626

27-
A file with the name, title, a brief description of the extension, and the access type it should have on being created
27+
The Connect Gallery displays apps, dashboards, and reports that can be easily
28+
added to Posit Connect servers.
2829

29-
```{filename="connect-extension.toml"}
30-
{{< include _template/connect-extension.toml >}}
30+
This section covers how to ready your content for the gallery, add it, and
31+
release new updates.
32+
33+
## Additional Requirements
34+
35+
### The `extension` section in `manifest.json`
36+
37+
Content in the gallery requires some additional details in the `manifest.json`
38+
file to display, install on Connect, and automatically release using automation
39+
in this repository.
40+
41+
Below is an example of the additional details that need to be manually added
42+
to the `manifest.json`:
43+
44+
```json {filename="manifest.json"}
45+
{
46+
...
47+
"extension": {
48+
"name": "my-content-name",
49+
"title": "My Content Name",
50+
"description": "A lovely, detailed description of the content.",
51+
"homepage": "https://github.com/posit-dev/connect-extensions/tree/main/extensions/my-content-name",
52+
"version": "0.0.0"
53+
}
54+
}
55+
```
56+
57+
It is recommended to begin with `"version": "0.0.0"` to avoid triggering a
58+
release during development of your content. When you are ready to release to
59+
the gallery check the [Adding content to the Connect Gallery](#adding-content-to-the-connect-gallery) section.
60+
61+
### Language version constraints
62+
63+
To ensure that content in the gallery is installable on as many Posit Connect
64+
servers as possible we use the language version constraints feature to broaden
65+
the language versions Connect can use for a piece of content.
66+
67+
All content in the gallery should include `requires` specifications for the
68+
language(s) it utilizes.
69+
70+
Here is an example of what needs to be included in a `manifest.json`:
71+
72+
```json {filename="manifest.json"}
73+
{
74+
...
75+
"environment": {
76+
"python": {
77+
"requires": ">=3.8, <4"
78+
},
79+
"r": {
80+
"requires": ">=4.2, <5"
81+
}
82+
},
83+
...
84+
}
3185
```
86+
87+
## Adding content to the Connect Gallery
88+
89+
Once your content has the requirements above it is ready to be added to the
90+
Connect Gallery.
91+
92+
The Connect Gallery uses GitHub Workflows to automate releases of new content
93+
when pull requests in this repo merge into `main`.
94+
95+
To add content to the Connect Gallery, follow the steps below:
96+
97+
### Adding simple content
98+
99+
"Simple content" refers to content that can be bundled into a TAR file without
100+
any additional steps. Most content will fall into this category.
101+
102+
::: {.callout-note}
103+
If you can run
104+
```bash
105+
tar -czf my-extension-name.tar.gz ./extensions/my-extension-name
106+
```
107+
and the resulting TAR file can be published by uploading the bundle to Posit
108+
Connect, then it is piece of simple content.
109+
:::
110+
111+
To add simple content look for the [`simple-extension-changes` section in the `.github/workflows/extensions.yml`](https://github.com/posit-dev/connect-extensions/blob/main/.github/workflows/extensions.yml#L31)
112+
file and add a new filter:
113+
114+
```yml
115+
filters: |
116+
...
117+
my-content-name: extensions/my-content-name/**
118+
```
119+
120+
A good example is how `reaper` is setup.
121+
122+
This will make any code changes to your content trigger a few things:
123+
124+
- lint: ensuring your content has everything it needs to be added to the
125+
gallery
126+
- package: creating a TAR file of the content's directory to test in pull
127+
requests and to be released
128+
- release: When the `version` in the `manifest.json` is incrased and merged to
129+
`main`, releases the content to users of Posit Connect
130+
131+
Lastly set the `version` in the `manifest.json` file to your initial release.
132+
133+
When the changes above are merged the first release will be kicked off, and
134+
your content will be in the gallery. 🚀
135+
136+
### Adding custom built content
137+
138+
"Custom built content" refers to content that requires additional steps prior to
139+
be being packaged into a TAR file.
140+
141+
Setting up custom built content is a bit more complex since it involves
142+
setting up the environment needed to build the content.
143+
144+
#### Creating a custom workflow
145+
146+
To faciliate control over how the content is being built we utilize custom
147+
GitHub Workflows. See the [Creating a custom workflow](docs/creating-a-custom-workflow.qmd)
148+
guide how to get started.
149+
150+
#### Calling the custom workflow
151+
152+
Once the custom workflow is created we need to head back to the general
153+
[.github/workflows/extensions.yml](https://github.com/posit-dev/connect-extensions/blob/main/.github/workflows/extensions.yml)
154+
file.
155+
156+
It is recommended to see how `publisher-command-center` is setup as an example
157+
for how to use your new custom workflow.
158+
159+
Once your custom workflow is setup, set the `version` in the `manifest.json`
160+
file to your initial release.
161+
162+
When the changes above are merged the first release will be kicked off, and
163+
your content will be in the gallery. 🚀
164+
165+
## Updating content in the Connect Gallery
166+
167+
To update already released content in the Connect Gallery simply increment the
168+
`version` field in the `extension` section of the `manifest.json` file and open
169+
a pull request with the changes.
170+
171+
```json {filename="manifest.json"}
172+
{
173+
...
174+
"extension": {
175+
...
176+
"version": "1.1.0"
177+
}
178+
}
179+
```
180+
181+
When that pull request is merged, GitHub Workflows will automatically create a
182+
new GitHub Release for the content changed, update the content list, and update
183+
Connect Gallery.
184+
185+
### Checking if your extension will release
186+
187+
If you would like to check if merging a pull request will trigger a new release
188+
you can do that by looking at the logs for the GitHub Actions.
189+
190+
Click on the "Checks" tab for a Pull Request and look at the Extension Workflow
191+
run.
192+
193+
Click on the Job related to the content being updated and view the logs for the
194+
`/./.github/actions/release-extension` action.
195+
196+
It will either say:
197+
198+
> The manifest version is '1.1.0' and the released version is '1.0.0'
199+
>
200+
> 🚀 Will release! The manifest version is greater than the released version.
201+
202+
or:
203+
204+
> The manifest version is '1.0.0' and the released version is '1.0.0'
205+
>
206+
>😴 Holding back from release: The manifest version is not greater than the released version.
207+
208+
## Manually testing content
209+
210+
Packaged TAR files are included as artifacts in the Extension Workflow runs.
211+
212+
Click on the "Checks" tab for a Pull Request and look at the Extension Workflow
213+
run. At the bottom, "Artifacts" are available, and if your content changed
214+
in the Pull Request then a `my-extension-name.tar.gz` file will be available.
215+
216+
It can be downloaded, and tested using the publish via bundle feature in Posit
217+
Connect.
218+
219+
## Removing a release from the Connect Gallery
220+
221+
If released content needs to be reverted, or content removed entirely, follow
222+
the steps below:
223+
224+
### Removing a single release
225+
226+
Open a pull request to remove the release:
227+
228+
1. Remove the release from the content list in `extension.json`
229+
- If the removed release is the latest release, update the `latestVersion`
230+
field for that piece of content to the previous release
231+
- Versions are sorted in descending order, so the latest release should be
232+
the first element in the `versions` array
233+
2. Revert the content's `version` in the `manifest.json` file to the previous
234+
release
235+
236+
Once the pull request is merged continue with the steps below:
237+
238+
1. Remove the associated release from the [GitHub Releases page](https://github.com/posit-dev/connect-extensions/releases).
239+
2. Remove the associated tag from the [GitHub Tags page](https://github.com/posit-dev/connect-extensions/tags).
240+
241+
### Removing an entire piece of content
242+
243+
Removing an entire piece of content from the gallery is similar to removing a single release, but
244+
with a few additional notes:
245+
246+
- Instead of removing a single list from the content list in `extension.json`
247+
remove the entire content object.
248+
- Instead of reverting the `version` in the `manifest.json` file to the previous
249+
release, instead set the version to `0.0.0` to avoid a release.
250+
251+
And after the pull request is merged:
252+
253+
- Remove all associated releases for the content from the [GitHub Releases page](https://github.com/posit-dev/connect-extensions/releases).
254+
- Remove all associated tags for the content from the [GitHub Tags page](https://github.com/posit-dev/connect-extensions/tags).
255+
256+
# Removing Content
257+
258+
Removing content from the `extensions/` subdirectory that has already been
259+
added to the Connect Gallery requires that you follow instructions in the
260+
above [Removing an entire piece of content](#removing-an-entire-piece-of-content)
261+
section.
262+
263+
In addition references to the content in GitHub workflows will need to removed.

‎docs/creating-a-custom-workflow.qmd‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Creating a custom workflow
3+
---
4+
5+
Most custom workflows will have common steps. They utilize handy
6+
[composite GitHub Actions](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action)
7+
in the repository.
8+
9+
A good place to start is looking at examples of custom workflows already in the
10+
repository like the [Publisher Command Center workflow](https://github.com/posit-dev/connect-extensions/blob/main/.github/workflows/publisher-command-center.yml).
11+
12+
## Custom Workflow Template
13+
14+
Use the template below to get started. It contains inline comments to explain
15+
each section.
16+
17+
Replace the `EXTENSION_NAME` variable with your content's name, and add the
18+
custom build steps needed for your content. The custom steps will entirely
19+
depend on your content and what environment it needs to setup.
20+
21+
```yaml {filename=".github/workflows/my-custom-content.yml"}
22+
name: My Custom Content
23+
24+
# Re-usable workflows use the `workflow_call` trigger
25+
# https://docs.github.com/en/actions/sharing-automations/reusing-workflows#creating-a-reusable-workflow
26+
on:
27+
workflow_call:
28+
29+
# Setup the environment with the extension name for easy re-use
30+
# Also set the GH_TOKEN for the release-extension action to be able to use gh
31+
env:
32+
EXTENSION_NAME: my-content-name
33+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
34+
35+
jobs:
36+
extension:
37+
runs-on: ubuntu-latest
38+
defaults:
39+
run:
40+
working-directory: ./extensions/${{ env.EXTENSION_NAME }}
41+
42+
steps:
43+
# Checkout the repository so the rest of the actions can run with no issue
44+
- uses: actions/checkout@v4
45+
46+
# We want to fail quickly if the linting fails, do that first
47+
- uses: ./.github/actions/lint-extension
48+
with:
49+
extension-name: ${{ env.EXTENSION_NAME }}
50+
51+
# ---
52+
# Add Custom Build Steps Here
53+
# ---
54+
55+
# Now that the extension is built we need to upload an artifact to pass
56+
# to the package-extension action that contains the files we want to be
57+
# included in the extension
58+
# This only includes necessary files for the extension to run leaving out
59+
# the files that were used to build the /dist/ directory
60+
- name: Upload built extension
61+
uses: actions/upload-artifact@v4
62+
with:
63+
name: ${{ env.EXTENSION_NAME }}
64+
# Replace the below with the files your content needs
65+
path: |
66+
extensions/${{ env.EXTENSION_NAME }}/dist/
67+
extensions/${{ env.EXTENSION_NAME }}/requirements.txt
68+
extensions/${{ env.EXTENSION_NAME }}/app.py
69+
extensions/${{ env.EXTENSION_NAME }}/manifest.json
70+
71+
# Package up the extension into a TAR using the package-extension action
72+
- uses: ./.github/actions/package-extension
73+
with:
74+
extension-name: ${{ env.EXTENSION_NAME }}
75+
artifact-name: ${{ env.EXTENSION_NAME }}
76+
77+
# Release the extension using the release-extension action
78+
# Will only create a GitHub release if merged to `main` and the semver
79+
# version has been updated
80+
- uses: ./.github/actions/release-extension
81+
with:
82+
extension-name: ${{ env.EXTENSION_NAME }}
83+
```

0 commit comments

Comments
 (0)