Skip to content

feat(sources): propose new source releases automatically - #12

Draft
pimlock wants to merge 1 commit into
mainfrom
feat/release-sync/pimlock
Draft

pimlock wants to merge 1 commit into
mainfrom
feat/release-sync/pimlock

Conversation

@pimlock

@pimlock pimlock commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Summary

New source releases no longer need a hand-edited sources.yml (as in #11 for Go SDK v0.1.9). The docs repo polls for them, the same pull model the SDK repos use to follow core. Source repos don't dispatch anything.

  • scripts/release-sync.mjs lists each source's tags with git ls-remote --tags (new listTags in assembler/fetch.mjs). It adds the stable releases (vX.Y.Z or X.Y.Z; -pre.N, -rc.N and other suffixes are skipped) that are newer than the newest listed version. They go at the top of versions, newest first, as { name: "X.Y.Z", ref: vX.Y.Z }. The file is edited as text, so comments and layout are kept. A second run changes nothing. Older tags are never added, so a release removed by hand stays removed. Options: --dry-run and --json (title and body for the PR). It also runs as mise run release-sync.
  • .github/workflows/release-sync.yml runs daily and on workflow_dispatch. It keeps one PR open from the fixed release-sync branch, titled for example chore(sources): publish sdk-go 0.1.9:
    • The branch is rebuilt from main. It is force-pushed only when the proposed sources.yml changes; then the open PR's title and body are updated.
    • When main already lists every release, an open proposal is closed.
    • A proposal a maintainer closed isn't reopened until another release changes the title.
    • Commits are signed off by the App's bot user (DCO).
  • test/release-sync.test.mjs: unit tests, plus end-to-end runs against local git repos with release, pre-release, annotated and lightweight tags.
  • README and CONTRIBUTING: how release sync works and what it needs. The README's Versions column is removed because it would go stale; sources.yml is the list.

Run against the real sources.yml (2026-11-19, main without #11)

$ node scripts/release-sync.mjs --dry-run
sdk-go: add 0.1.9 (v0.1.9)
     versions:
+      - { name: "0.1.9", ref: v0.1.9 }
       - { name: "0.1.8", ref: v0.1.8 }

That is the same entry #11 adds by hand. A second run prints No new releases. Once #11 merges, the first scheduled run finds nothing.

Maintainer setup

The workflow fails at the token step until this is done:

  1. A GitHub App installed on ai-openshell/docs with Contents: read and write and Pull requests: read and write. The sdk-go sdk-bot App can be reused if it is installed here; otherwise create a docs bot.
    • The App token is needed because PRs opened with the default GITHUB_TOKEN don't trigger other workflows, so Site (lint, tests, build) would not run on the proposal.
    • The Netlify deploy preview and DCO run either way.
  2. An environment named docs-bot with deployment branches limited to main, so a pushed branch can't mint a bot token. It holds two secrets:
    • DOCS_BOT_CLIENT_ID: the App's client ID.
    • DOCS_BOT_PRIVATE_KEY: a private key of the App.

After merging, run Release sync once from the Actions tab to check the setup.

Follow-up (not in this PR): dev pages on Netlify go stale

Site rebuilds hourly to pick up each source's main, but it publishes to GitHub Pages, which isn't set up. Netlify, the live host, rebuilds only on pushes to this repo, so the dev versions there fall behind their source branches. The pull-based fix:

  • Add a Netlify build hook for main and store its URL as a repo secret, such as NETLIFY_BUILD_HOOK.
  • Add a scheduled workflow (hourly, like Site) that POSTs to it.
  • Optionally, drop the GitHub Pages deploy and the repository_dispatch trigger from Site.

Testing

  • npm test: 38 pass.
  • npm run lint: clean.
  • actionlint (with shellcheck) on the new workflow: clean.
  • The workflow itself has not run yet; it needs the App and environment above.

Add scripts/release-sync.mjs, which lists each source's tags with git ls-remote and adds the stable releases newer than the newest listed version to sources.yml, editing the text so comments and layout survive.

The daily Release sync workflow runs it and keeps one pull request open from the release-sync branch, using a GitHub App token so the Site workflow runs on it.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@netlify

netlify Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for ai-openshell-docs ready!

Name Link
🔨 Latest commit 01289d1
🔍 Latest deploy log https://app.netlify.com/projects/ai-openshell-docs/deploys/6aff6cbeaf6be2b434524a08
😎 Deploy Preview https://deploy-preview-12--ai-openshell-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant