Repository navigation
Bootstrap the Solutions monorepo - #299
Closed
JakeSCahill wants to merge 60 commits into
Closed
JakeSCahill wants to merge 60 commits into
JakeSCahill wants to merge 60 commits into
Conversation
The labs content is frozen pending migration into solutions. The relative symlinks under labs-docs/modules keep their depth, so every page still resolves. build-docs.yml stays as the single Netlify trigger.
new-solution.sh scaffolds a solution, check-metadata.sh enforces the metadata contract, changed-solutions.sh derives the CI matrix, run-doc-detective.sh merges the shared Doc Detective base config, and verify-lib.sh / wait-for.sh back each solution's verify script. The local Antora playbook builds both the solutions and the frozen labs component.
Overview and step page templates carry every attribute of the metadata contract as placeholders that check-metadata.sh refuses, plus a compose stack (Redpanda, Console, rpk helper) with healthchecks, the Makefile contract, a verify script, sample data, and Doc Detective specs with a setup/teardown split.
ci.yml and nightly.yml share one reusable job (test-solution.yml) so the compose up, seed, verify, log-capture, and teardown steps stay identical. release.yml tags <slug>/<version> and publishes <slug>-<version>.zip for every authored version without a tag, then triggers one Netlify build.
CONTRIBUTING.md is the canonical writer guide; CLAUDE.md and AGENTS.md mirror it for agents. CODEOWNERS routes review to the docs team, LICENSE is Apache-2.0, SECURITY.md covers reporting. README.md describes the monorepo and marks the labs content as frozen. The old repo-level labs contributing guide moves under labs-docs.
Antora resolves a bare relative url against the playbook's directory (tools/), so use the ~+ working-directory token, which is what the old docs/local-antora-playbook.yml did.
Antora drops dotfiles and files without an extension, so the scaffold symlinks .env.example as env.example and Makefile as Makefile.mk, and check-metadata.sh fails on any attachment Antora would skip.
tools/local-antora-playbook.yml builds both components; the old file's start paths no longer matched anything after the move to labs-docs.
docs/modules/examples holds runnable code for Product Docs tutorials, included on pages via include::solutions:examples:example$ and shipped as public attachment zips. It is not a solution: the slug is reserved and the metadata and matrix tools skip it.
tools/lib.sh holds SLUG_RE and RESERVED_IDS. check-metadata joins backslash-continued attribute lines, finds nested step pages, scans page bodies for leftover placeholders, env conditionals and repo links, and treats a missing category list as an error in CI. changed-solutions selects every solution when tools/, templates/, or the shared test job change. run-doc-detective puts the step specs in the merged config (--input is not variadic) and only kills the engine's node process.
Releases are decided by gh release view and created with gh release create --target, so no orphan tag can block a version; drafts are never released; the job runs only on main and posts the Netlify hook once per run, replacing build-docs.yml. docs.yml runs on every PR and fails on unresolved includes or missing images; nightly gets actions: read; dependabot drops the empty globs until solutions exist.
BSD mktemp only substitutes trailing X characters, so the old template dd-config-<slug>.XXXXXX.json was created literally and two runs of the same slug shared one file.
✅ Deploy Preview for redpanda-labs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
… from a running stack
…d; run-doc-detective generates them
…outputs, no committed step spec
…request for regenerated media
…lated-docs for single pages
… the Antora proof clone
…on, or a published solution has no assumes
…ed command writes
…t is the detector
The attribute restated what the page already said twice over. The difficulty rubric defines intermediate as one named Redpanda concept plus reading one language, and the overview's Prerequisites section states the concrete requirement: versions, resources, and the tools needed on the host. "Docker, topics, reading Go" sat between the two adding nothing checkable. Two of the five solutions never set it and nothing noticed, because the warning only fired for a published solution and all five are still drafts. CONTRIBUTING.md now points writers at Prerequisites instead, the scaffold no longer prompts for it, and check-metadata.sh drops the warning. The difficulty rubric and its "assumed knowledge" guidance are unchanged: the label still sorts a solution against its siblings.
The "Redpanda Cloud Serverless" tab on a solution's overview page is the one path nothing exercises: the local stack proves the solution, and the Cloud tab is prose nobody runs. This adds a reusable job that runs a solution the way that tab tells a reader to, and calls it from the nightly beside the local run. Serverless rather than a BYOC cluster on purpose. The flagship's tab documents Serverless, including that you cannot lower the cluster's segment.ms floor, so a BYOC run would pass a test for prose that was never published. A solution opts in by shipping env.cloud.example, the file its page already includes, so there is no list of cloud-capable solutions to maintain. A solution without one skips. A solution with one but no cloud-acls.conf fails loudly instead, because that is an unfinished solution rather than an opt-out, and falling back to a broad grant to keep the run green is exactly the wrong answer on a shared cluster. Two properties the cluster being shared makes load-bearing: The user is named for the run and granted only what cloud-acls.conf declares, which is the same grant the page documents. There is no wildcard fallback. Teardown deletes a topic only when it is both absent from a snapshot taken before the stack started and under the declared prefix. Two independent conditions, because deleting someone else's topic is the one mistake here that cannot be undone. It runs on failure and on cancellation. Not wired into ci.yml: the cluster is shared and a run takes minutes, so this is a nightly signal, not a per-pull-request gate. NOT YET RUN. It needs RP_CLOUD_CLIENT_ID, RP_CLOUD_CLIENT_SECRET and RP_CLOUD_SERVERLESS_CLUSTER_ID in the repository settings, which do not exist yet, and the first run is the thing that will find the mistakes in it.
Both were flags I assumed rather than checked, and both would have failed on the workflow's first run: `rpk topic list -f '%n'` does not exist. There is no -f on that command, only --format (json, yaml, text, wide). The before and after topic snapshots now use --format json with jq, which matters more than most of the file: those snapshots are what stops the teardown deleting a topic the run did not create on a shared cluster. Had this stayed, the snapshot would have been empty and the teardown would have skipped deleting anything, which is the safe direction but would have left every run's topics behind. `rpk profile print -o yaml` errors with "unknown shorthand flag: 'o'". Bare `rpk profile print` already emits YAML, so the flag was never needed. Verified against rpk v26.2.1 rather than from the help text alone: both awk extractions were run against a real Serverless profile and return the bootstrap server and the Schema Registry URL. RPK_CLOUD_CLIENT_ID and RPK_CLOUD_CLIENT_SECRET are confirmed as the environment variable names rpk reads for client credentials.
…e facets
page-solution-use-cases was free text and nothing consumed it, so it had
drifted into five different kinds of thing at once: a pattern (Real-time
analytics), a task (Kafka migration), an industry (Gaming), a business
outcome (Business continuity) and a constraint (Zero-downtime cutover). A
reader cannot filter on a mixed axis, and a free-text facet becomes a list of
near-duplicates ("CDC", "Change data capture") the moment a second author
writes one.
Split it into two axes with one reviewed vocabulary, the same mechanism
page-categories already uses: the industry is who the reader is, the use case
is what they are building. Anything else a solution wants to claim stays prose
in :description:, where it can be a sentence instead of a label.
solution-facets.yml is a ROOT partial, so the vocabulary travels with the
solutions rather than with the extension package, and adding a value is a
reviewed pull request. An unlisted value fails the build; check-metadata.sh
carries the same check so the feedback arrives before a full build does.
Also drop the modify-redirects require from the local playbook. That
extension was replaced in 2024 and then removed from
docs-extensions-and-macros, so `npm run build` failed at startup before
reaching any content.
Contributor
Author
|
Moved to the private solutions monorepo: https://github.com/redpanda-data/redpanda-solutions/pull/1 Same branch name, same head commit (dccaf44), same base in the new stack. Solution code now lives in |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of DOC-2182 (Labs to Solutions). Draft until the rename to
redpanda-data/solutionsis agreed.Turns this repo into the home of Redpanda Solutions while the existing Labs keep publishing:
docs/(thelabscomponent) moves tolabs-docs/unchanged; the docs-site labs content source must switch tostart_path: labs-docsin the same wave. Labs CI is removed because Labs content is frozen pending migration.docs/antora.ymlowns thesolutionscomponent (landing page, personas,relationships.yml, and an ungatedexamplesmodule for Product Docs tutorial code).tools/: scaffold (new-solution.sh), metadata checks, changed-solution matrix, shared verify library, Doc Detective runner, local Antora playbook.templates/solution/: the overview and step page templates, compose stack, Makefile, verify script, and Doc Detective specs a new solution starts from.<slug>/vX.Y.Zplus a bundle asset, then one Netlify build), nightly runs on latest images.CONTRIBUTING.mdis the Solutions writer guide;CLAUDE.mdandAGENTS.mddescribe the layout for agents.Do not merge before the docs-site playbook change that reads
labs-docs.