Skip to content

docs: move published docs to volcano-docs #373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
swkeever merged 2 commits into from
Nov 13, 2026
Merged

docs: move published docs to volcano-docs #373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b06d656
docs: move published docs to volcano-docs
swkeever Nov 13, 2026
7f9a37f
fix(deps): bump rack from 3.2.7 to 3.2.8
swkeever Nov 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 25 additions & 11 deletions .github/scripts/quickstart.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,31 @@
require 'timeout'
require_relative '../../spec/support/recording_server'

# Executes the unchanged public example with the isolated gem selected by smoke-gem.sh.
# Executes the public quickstart with the isolated gem selected by smoke-gem.sh.
class PackageQuickstart
# The public quickstart, as published in Kong/volcano-docs
# content/sdk/ruby/index.md ("Sign in and read a profile"). Change both together.
EXAMPLE = <<~'RUBY'

@github-actions github-actions Bot Nov 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Package quickstart check now runs a hand-copied snippet and can drift from the published quickstart

The check used to pull the quickstart out of docs/README.md, so changing the published example automatically changed what smoke-gem.sh ran against the built gem. Now EXAMPLE is a separate copy, kept in sync only by the comment "Change both together." If someone edits the quickstart in Kong/volcano-docs content/sdk/ruby/index.md, this check keeps passing on the old copy. It still prints Documented quickstart passed (.github/scripts/smoke-gem.sh:40), and maintainers/releasing.md:39 still calls it "the exact public quickstart." Neither is accurate any more. One fix is to have volcano-docs run its own snippet against a released gem. Another is to reword the message and the release guide so they say the check runs a local copy, not the published page.

Found by claude-opus-5-5

@github-actions github-actions Bot Nov 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Package check can drift from the published quickstart

EXAMPLE now duplicates the documentation, so a future volcano-docs edit can leave package CI exercising an older snippet. .github/scripts/smoke-gem.sh:40 still reports Documented quickstart passed, and maintainers/releasing.md describes it as the public quickstart. Clarify that the check validates a local copy, or validate the published snippet in the docs repository.

Found by gpt-6.1-sol

require "volcano"

client = Volcano::Client.new(
anon_key: ENV.fetch("VOLCANO_ANON_KEY"),
api_url: ENV.fetch("VOLCANO_API_URL", "https://api.volcano.dev")
)
session = client.auth.sign_in(
email: ENV.fetch("VOLCANO_USER_EMAIL"),
password: ENV.fetch("VOLCANO_USER_PASSWORD")
)
begin
user = client.auth.user
raise "Unexpected user" unless user.id == session.user_id

puts "Signed in as #{user.email}"
ensure
client.auth.sign_out
end
RUBY

USER = {
id: '22222222-2222-4222-8222-222222222222',
project_id: '11111111-1111-4111-8111-111111111111',
Expand Down Expand Up @@ -45,18 +68,9 @@ def configure(url)
)
end

def example
document = File.read(File.expand_path('../../docs/README.md', __dir__))
section = document.split("## Sign in and read a profile\n").fetch(1).split("\n## ").first
examples = section.scan(/```ruby\n(.*?)\n```/m).flatten
raise 'Expected one complete documented quickstart' unless examples.length == 1

examples.first
end

def execute
previous_stdout = $stdout
File.write('quickstart.rb', example)
File.write('quickstart.rb', EXAMPLE)
output = StringIO.new
$stdout = output
Timeout.timeout(30) { load File.expand_path('quickstart.rb') }
Expand Down
16 changes: 0 additions & 16 deletions .github/workflows/lint-docs.yml
View file
Open in desktop

This file was deleted.

4 changes: 3 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,6 @@
automation.
- Keep native unit, type, build, and package checks here. Hosting owns behavioral
acceptance scenarios and bindings; coordinate changes with `Kong/volcano-hosting`.
- Keep maintainer guidance under `maintainers/`; `docs/` is published.
- Keep maintainer guidance under `maintainers/`.
- Public SDK docs live in `Kong/volcano-docs` under `content/sdk/ruby`. When
user-facing behavior changes, open a companion PR there and link the two PRs.
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,9 @@ actual live results separately from discovery or package checks.

### Documentation and release boundaries

`docs/` is published to the developer documentation site. Put user-facing
examples there and maintainer instructions in this file or beside the code.
Public guides live in `Kong/volcano-docs` under `content/sdk/ruby` and publish
to https://docs.volcano.dev/sdk/ruby. Put user-facing examples there in a
companion PR, and maintainer instructions in this file or beside the code.
Keep equivalent language examples current in the same coordinated change.
Package checks validate artifacts; they do not authorize publication. Treat
registry-installed quickstarts and release approval as separate release work.
2 changes: 1 addition & 1 deletion Gemfile.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ GEM
protocol-websocket (0.21.2)
protocol-http (~> 0.2)
racc (1.8.1)
rack (3.2.7)
rack (3.2.8)
rainbow (3.1.1)
rake (13.4.2)
rb-fsevent (0.11.2)
Expand Down
14 changes: 7 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

Official Ruby SDK for Volcano. Requires Ruby 3.3 or later.

Start with the [Ruby quickstart](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/README.md).
Start with the [Ruby quickstart](https://docs.volcano.dev/sdk/ruby).

@github-actions github-actions Bot Nov 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Links in already-published gem READMEs to blob/main/docs/ will 404 once docs/ is deleted

Released gems up to 0.35.1 bundle a README.md whose links point to https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/README.md, docs/authentication.md, docs/functions.md, docs/logs.md and docs/locks.md. After this PR those GitHub URLs return 404 for anyone reading an installed gem's README or following an old external link. A small docs/README.md stub that points to https://docs.volcano.dev/sdk/ruby would keep those links working. Leaving them broken is also acceptable.

Found by claude-opus-5-5


See [Authentication](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/authentication.md) for account, session, email, and OAuth workflows.
See [Authentication](https://docs.volcano.dev/sdk/ruby/authentication) for account, session, email, and OAuth workflows.

## Install

Expand Down Expand Up @@ -393,7 +393,7 @@ without changing credentials. Without a refresh token, `refresh_session` raises
`Volcano::Error::AuthenticationError`. `sign_out` clears local state and revokes the server
session when the access JWT contains a readable UUID `session_id`. Supplied credentials require both a refresh token and an access JWT with a readable UUID
`session_id` to enable refresh.
See the [token bootstrap example](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/README.md#use-a-supplied-access-token).
See the [token bootstrap example](https://docs.volcano.dev/sdk/ruby#use-a-supplied-access-token).

### Adopt an existing session

Expand Down Expand Up @@ -493,7 +493,7 @@ prevents replay under another identity. The call preserves its original payload
A function's own response, HTTP 403, or a network failure never triggers this retry.
Anonymous and service keys do not refresh.

See the [functions guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/functions.md).
See the [functions guide](https://docs.volcano.dev/sdk/ruby/functions).

### Start and follow a durable execution

Expand Down Expand Up @@ -680,7 +680,7 @@ they started; the anon key, or another user, passes the execution's
`client_token:`, which only the creating start returns. Pass `project_id:` to
`send_message`, `list`, or `subscribe` to use the owner's route with a platform
user token or a project access token; `subscribe` reads back over it. See the
[functions guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/functions.md#message-a-durable-execution).
[functions guide](https://docs.volcano.dev/sdk/ruby/functions#message-a-durable-execution).

### Read project logs

Expand Down Expand Up @@ -708,7 +708,7 @@ events. Pass `next_cursor` back as `cursor` to continue a search. `activity`
returns immutable time buckets using the same resource selector and query
syntax. Both methods require a platform user token or a project access token.
A `read_only` project token is sufficient; end-user sessions cannot read project logs.
See the [logs guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/logs.md).
See the [logs guide](https://docs.volcano.dev/sdk/ruby/logs).

### Query a database

Expand Down Expand Up @@ -890,7 +890,7 @@ Acquisition accepts caller-owned UUID `token` and `request_id` values and retrie
an ambiguous transport failure or HTTP 503 once with the same request and credential.
Retain those IDs to recover an uncertain acquisition. Other lock methods accept
`request_id`; block-scoped helpers forward initial IDs only to acquisition.
See the [lock guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/locks.md)
See the [lock guide](https://docs.volcano.dev/sdk/ruby/locks)
for examples and fencing requirements.

`locks.get` returns immutable lock availability, expiry, and fencing-token
Expand Down
133 changes: 0 additions & 133 deletions docs/README.md
View file
Open in desktop

This file was deleted.

Loading
Loading