Add some dev-notes about cloudsmith publishing

Author: cderv

dev-docs/checklist-make-a-new-quarto-prerelease.md

@@ -11,3 +11,5 @@
   - New release prerelease should be on Github at <https://github.com/quarto-dev/quarto-cli/releases>
   - A new tag should be on main for the new prerelease version
   - `version.txt` on main should have been updated by the workflow to the pre-release version just released: https://github.com/quarto-dev/quarto-cli/blob/main/version.txt
+
+Note: Cloudsmith publishing is skipped for prereleases (only runs for stable releases).

dev-docs/checklist-make-a-new-quarto-release.md

@@ -72,10 +72,12 @@
           - Published to: <https://pypi.org/project/quarto-cli/>
       - Take a sip of tea ☕, bask in the glory of automation.
   - Others installers
+    - Cloudsmith: Automatically published by Build Installers workflow. No action needed.
+      - See [cloudsmith-publishing.md](cloudsmith-publishing.md) for manual republishing if needed.
     - conda-forge: An automated PR will be created to update the package version in the feedstock <github.com/conda-forge/quarto-feedstock>
       - This is community maintained, so no action is needed from us - except maybe helping if there are issues with the PR. We are assigned as reviewers to the PR.
-      - Winget: An automated PR will be created by a winget bot in <github.com/microsoft/winget-pkgs/>.
-        - This is community maintained, so no action is needed from us.
-      - Scoop: This will be updated automatically in the manifests repo. No action is needed from us. Maintained as personal project by @cderv.
-      - Homebrew: This is automated through an homebrew bot to update the cask <https://github.com/Homebrew/homebrew-cask>
-        - Manifest: <https://github.com/Homebrew/homebrew-cask/blob/master/Casks/q/quarto.rb>
+    - Winget: An automated PR will be created by a winget bot in <github.com/microsoft/winget-pkgs/>.
+      - This is community maintained, so no action is needed from us.
+    - Scoop: This will be updated automatically in the manifests repo. No action is needed from us. Maintained as personal project by @cderv.
+    - Homebrew: This is automated through an homebrew bot to update the cask <https://github.com/Homebrew/homebrew-cask>
+      - Manifest: <https://github.com/Homebrew/homebrew-cask/blob/master/Casks/q/quarto.rb>

dev-docs/checklist-make-a-new-stable-quarto-release.md

@@ -37,10 +37,12 @@
 - [ ] Update the stable changelog by moving entries to the "in previous release". Use "[release checklist]" in the commit message to make it easier to spot if a new release is needed next month.
 
 - Others installers
+  - Cloudsmith: Automatically published by Build Installers workflow. No action needed.
+    - See [cloudsmith-publishing.md](cloudsmith-publishing.md) for manual republishing if needed.
   - conda-forge: An automated PR will be created to update the package version in the feedstock <github.com/conda-forge/quarto-feedstock>
     - This is community maintained, so no action is needed from us - except maybe helping if there are issues with the PR. We are assigned as reviewers to the PR.
-    - Winget: An automated PR will be created by a winget bot in <github.com/microsoft/winget-pkgs/>.
-      - This is community maintained, so no action is needed from us.
-    - Scoop: This will be updated automatically in the manifests repo. No action is needed from us. Maintained as personal project by @cderv.
-    - Homebrew: This is automated through an homebrew bot to update the cask <https://github.com/Homebrew/homebrew-cask>
-      - Manisfest: <https://github.com/Homebrew/homebrew-cask/blob/master/Casks/q/quarto.rb>
+  - Winget: An automated PR will be created by a winget bot in <github.com/microsoft/winget-pkgs/>.
+    - This is community maintained, so no action is needed from us.
+  - Scoop: This will be updated automatically in the manifests repo. No action is needed from us. Maintained as personal project by @cderv.
+  - Homebrew: This is automated through an homebrew bot to update the cask <https://github.com/Homebrew/homebrew-cask>
+    - Manisfest: <https://github.com/Homebrew/homebrew-cask/blob/master/Casks/q/quarto.rb>

dev-docs/cloudsmith-publishing.md

@@ -0,0 +1,65 @@
+# Cloudsmith Package Publishing
+
+Publishes Linux packages (DEBs and RPMs) to Cloudsmith's `posit/open` repository.
+
+**Workflow**: [.github/workflows/publish-cloudsmith.yml](../.github/workflows/publish-cloudsmith.yml)
+
+## Automatic Publishing
+
+Called automatically by `create-release.yml` for stable releases (non-prereleases).
+
+## Manual Publishing
+
+Use for:
+- Republishing older releases
+- Fixing package issues
+- Testing with dry-run
+
+### Steps
+
+1. Go to [Actions → Publish to Cloudsmith](https://github.com/quarto-dev/quarto-cli/actions/workflows/publish-cloudsmith.yml)
+2. Click "Run workflow"
+3. Configure:
+   - **version**: `v1.8.26` (release tag)
+   - **dry-run**: Check for testing, uncheck for production
+4. Run workflow
+
+### Dry-Run First
+
+**Always test with dry-run before production:**
+
+```yaml
+dry-run: true   # Test - validates but doesn't publish
+dry-run: false  # Production - publishes to Cloudsmith
+```
+
+Dry-run downloads packages and validates parameters without pushing to Cloudsmith.
+
+## Required Assets
+
+Workflow expects these in the GitHub release:
+
+```
+quarto-${VERSION}-linux-amd64.deb
+quarto-${VERSION}-linux-arm64.deb
+quarto-${VERSION}-linux-x86_64.rpm
+quarto-${VERSION}-linux-aarch64.rpm
+```
+
+Verify with:
+```bash
+gh release view v1.8.26 --json assets --jq '.assets[].name' | grep -E '(deb|rpm)'
+```
+
+## Architecture
+
+- **Validation**: Checks assets exist via GitHub API
+- **Matrix**: 4 parallel jobs (deb/rpm × x86_64/aarch64)
+- **Publishing**: Uses `cloudsmith push` with `--republish` flag
+- **Repository**: `posit/open/any-distro/any-version` (distribution-agnostic)
+
+## Troubleshooting
+
+**Assets missing**: Run [Build Installers](https://github.com/quarto-dev/quarto-cli/actions/workflows/create-release.yml) workflow to rebuild packages
+
+**Authentication failed**: Check `CLOUDSMITH_API_KEY` secret in repository settings