Repository navigation
feat(docs): author all docs here and stop syncing from product repos - #170
Conversation
volcano-hosting 22940d7dd463 volcano-sdk-js a174c88d9431 volcano-sdk-python 340c9a3eabb0 volcano-sdk-ruby e3082ccaf707 volcano-cli 19e81bec7677
volcano-hosting 958dd2ad5a02
AI review: no P0-P2 findingsThis PR stops the daily sync that copied docs in from the product repos, so every page is now written here. It deletes the sync workflow, script and config, adds a final snapshot of the product docs, and deletes the copied ⚪ P3
Not checked: The AI review read the diff, the code, and the PR's text; it ran no tests or builds and read nothing outside this repository.
Human review: not needed |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| commit-message: | ||
| prefix: "chore" | ||
| include: "scope" | ||
| ignore: |
There was a problem hiding this comment.
⚪ P3: Examples Dependabot entry says React majors are held, but the ignore list leaves them out
The comment above the new examples entry says "Next.js and React majors follow the runtimes Volcano supports". The ignore list only holds back majors for @volcano.dev/*, next and eslint-config-next. frontend-auth-nextjs, realtime-chat and frontend-function-routes/web depend on react, react-dom and @types/react. When a React major ships, Dependabot will open an examples-major PR that bumps React while Next stays put. Either add react, react-dom, @types/react and @types/react-dom to ignore, or drop React from the comment.
Found by claude-opus-5-5
There was a problem hiding this comment.
🟡 Changes recommended
The CI workflow unnecessarily checks unrelated examples for docs-only changes, and the documentation instructs readers to use CLI commands absent from the referenced snapshot.
2 open issues
What changed in this PR
Moves Volcano documentation ownership into this repository, replacing automated product-repository syncs with companion docs PRs merged when features reach production.
Changes:
- Removes sync infrastructure and adds centralized authoring and release-timing guidance.
- Imports the final documentation snapshot, including function previews, tracked migrations, LavaFlow updates, and bounded database pooling.
- Adds example-app type checks and dependency updates while correcting links affected by the move.
| File | Description |
|---|---|
src/lib/content-file.mjs |
Updates comments to remove sync references. |
spec/writing.md |
Adds linking, wording, and release-timing rules. |
spec/markdown-format.md |
Updates the format contract for local ownership. |
spec/ci-caller.example.yml |
Removes the product-repo CI template. |
spec/AGENTS.snippet.md |
Removes obsolete product-repo instructions. |
source.config.ts |
Updates the content-ownership comment. |
source-revisions.json |
Removes sync revision tracking. |
scripts/sync-docs.sh |
Removes product-repository copying. |
scripts/refuse-symlinks.sh |
Updates comments; preserves symlink checks. |
scripts/migrate-docs.mjs |
Removes the one-time migration utility. |
scripts/check-links.mjs |
Generalizes an unserved-assets comment. |
README.md |
Documents centralized ownership and editing. |
package.json |
Removes the migration command. |
docs.config.yaml |
Removes the sync-source manifest. |
content/platform/storage/overview.md |
Links to the CLI section. |
content/platform/projects/git-deploy.md |
Updates TypeScript, shared-code, settings, and migration guidance. |
content/platform/projects/export-to-git.md |
Updates preview restrictions and TypeScript guidance. |
content/platform/interfaces/mcp.md |
Refreshes LavaFlow tools and response limits. |
content/platform/index.md |
Adds links to new and updated guides. |
content/platform/guides/production.md |
Describes tracked deployment migrations. |
content/platform/guides/plans-and-limits.md |
Adds database connection safety limits. |
content/platform/guides/migrations.md |
Documents tracked CLI migration workflows. |
content/platform/guides/lavaflow.md |
Refreshes review, CI, integration, and outcome behavior. |
content/platform/guides/lavaflow-slack.md |
Adds clarification and requested-change workflows. |
content/platform/guides/lavaflow-aikido.md |
Adds Aikido integration setup and behavior. |
content/platform/guides/issues.md |
Documents build issues and source-map grouping. |
content/platform/getting-started/quickstart.md |
Updates migration tracking and upgrade guidance. |
content/platform/getting-started/installation.md |
Links to the CLI section. |
content/platform/functions/user-context.md |
Adopts bounded per-user database pools. |
content/platform/functions/upload-api.md |
Updates TSX and upload-layout rules. |
content/platform/functions/previews.md |
Adds preview lifecycle and availability guidance. |
content/platform/functions/logs.md |
Explains promoted-preview log behavior. |
content/platform/functions/environment-variables.md |
Documents synchronization skips for promoted previews. |
content/platform/functions/creating-functions.md |
Adds TSX, source-map, and shared-import guidance. |
content/platform/examples/database-pool-example/user-db-pool.js |
Adds a bounded per-user pool helper. |
content/platform/examples/database-pool-example/README.md |
Documents pool limits and helper packaging. |
content/platform/examples/database-pool-example/index.js |
Uses the helper and handles acquisition failures. |
content/platform/databases/rest-api.md |
Documents connection capacity and backpressure. |
content/platform/databases/importing-data.md |
Adds the CopyData message-size limit. |
content/platform/databases/direct-connection.md |
Expands pooling, protocol, and error guidance. |
content/platform/databases/connection-strings.md |
Updates session limits and idle timeouts. |
content/platform/databases/authentication-flow.md |
Reduces example pool sizes and adopts the helper. |
content/platform/authentication/security/project-access-tokens.md |
Updates LavaFlow token restrictions. |
content/platform/authentication/backend/function-integration.md |
Adopts bounded pools and temporary-failure responses. |
content/platform/api-reference/overview.md |
Refreshes capabilities and LavaFlow endpoints. |
content/platform/api-reference/functions.md |
Adds preview endpoints and updates upload inference. |
content/platform/api-reference/errors.md |
Updates LavaFlow authorization errors. |
content/cli/scripting.md |
Documents per-command project selection. |
content/cli/lavaflow.md |
Updates settings and issue-source output. |
content/cli/index.md |
Introduces the cloud project override. |
content/cli/functions.md |
Documents function layout and TypeScript precedence. |
content/cli/deploy.md |
Updates tracked migration deployment behavior. |
content/cli/databases.md |
Adds tracked migration commands and baselining. |
content/cli/connect.md |
Updates project-selection precedence. |
AGENTS.md |
Updates contributor guidance for centralized ownership. |
.gitignore |
Updates the content-packaging comment. |
.github/workflows/sync-docs.yml |
Removes automated sync PR creation. |
.github/workflows/examples.yml |
Adds example discovery and type-check jobs. |
.github/workflows/ci.yml |
Removes obsolete sync references from comments. |
.github/dependabot.yml |
Adds dependency updates for example apps. |
Review effort: Balanced
| dir=$(dirname "$package") | ||
| [ -f "$dir/tsconfig.json" ] || continue |
| ## Deploy a preview | ||
|
|
||
| ```bash | ||
| volcano cloud functions preview create api --name checkout-v2 --path ./functions/api |
| @@ -0,0 +1,131 @@ | |||
| name: Docs examples type-check | |||
|
|
|||
| # Type-checks the example apps under content/platform/examples that a PR | |||
There was a problem hiding this comment.
⚪ P3: Workflow says it type-checks only the examples a PR changes, but it checks all of them
The header comment, and the PR description, say the workflow "Type-checks the example apps under content/platform/examples that a PR changes". In practice, changed is only used as a yes/no switch: if any file under content/platform/examples or the workflow itself changed, the find loop puts every package.json + tsconfig.json directory into the matrix. Today that means a PR that touches only database-pool-example still type-checks both frontend-auth-nextjs and realtime-chat. This is harmless, but the comment misleads whoever maintains the workflow. Either reword it ("when a PR changes any example, type-checks every example app"), or keep only the example directories that contain a path in changed.
Found by claude-opus-5-5
Why
Docs were assembled by a daily sync that copied each product repo's
docs/intocontent/<section>/from that repo'smain. Now that a push tomaindeploys the site through Volcano's Git auto-deploy, that sync publishes docs for features that haven't reached production. A sync PR mixes changes from many source PRs, so it can't be split by release. The team agreed in #volcano-devs to make this repo the only place docs are written: a product change opens a companion PR here and merges it when the change is released.What changed
.github/workflows/sync-docs.yml,scripts/sync-docs.sh,source-revisions.json, thesourceslist indocs.config.yaml,scripts/migrate-docs.mjs,spec/ci-caller.example.yml, andspec/AGENTS.snippet.md.content/platform/api-reference/openapi.yaml. The site never served it (only.mdfiles become routes); the API reference pages already link tohttps://api.volcano.dev/openapi.yaml, which production serves..github/workflows/examples.yml, moved from volcano-hosting'sdocs-examples.yml: it type-checks the example apps undercontent/platform/examplesthat a PR changes. Add a Dependabot entry for those examples, also moved from volcano-hosting.spec/writing.md: the linking and wording rules from volcano-hosting's public-docs guide, plus a release-timing rule (merge a page about a new behavior when it reaches production).spec/markdown-format.md, and comments in CI,.gitignore, and scripts now say every page is authored here..github/workflows/lint-docs.yml(the reusable lint the product repos call) stays until their removal PRs merge; a follow-up removes it.Final snapshot
The second commit copies each product repo's docs at its current
main, the way the sync did, so nothing written before cutover is lost. It replaces the open sync PR #168, which can be closed. It also fixes links the sync would have rejected:user-db-pool.js, a source file the site can't serve. They now link it on GitHub.docs/folder on GitHub. They now link/cli.d23abe5(no docs change since958dd2a)a174c88340c9a3e3082cc19e81beRight before this merges, the snapshot is refreshed to the then-current
mainof each repo.Merge order
Testing
pnpm lint:docs content spec: docs OK.pnpm check:links: 214 routes OK.pnpm test:docsandpnpm test:actions: pass.pnpm lint: 0 errors (3 existingno-ternarywarnings insrc/components/sidebar/nav-tree.tsx).pnpm build: passes, including the search-index and server-trace checks.🤖 Generated with Claude Code