Hi Robert, Both ideas are great!
Having the guides in the web site makes sense to me, as this will increase their visibility. As for CI coverage, I agree that we should at least do something about it. Maybe instead of parsing the README files, how about we require from each getting-started guide to provide a CI verification script? This could hopefully simplify the logic for running those guides in CI. Thanks, Alex On Tue, Jan 20, 2026 at 11:55 AM Robert Stupp <[email protected]> wrote: > > Hi all, > > We have a nice collection of getting started guides in the source > repository [1]. > The user-targeting description of each guide is in a README.md file. > > I would like to start a discussion and gather feedback about two > topics regarding the getting-started guides: > > 1. Website: > The user facing getting-started guides are well written but not very > visible to users, because those are not on the web site. > What are your thoughts of moving the getting-started guides to the website? > > 2. CI coverage: > Most, actually all, getting-started guides include code snippets > referencing Docker compose files. > Manually verifying these code snippets and Docker compose files, > during initial contribution or when those are being updated, is quite > some work. > I _think_ we can automate the verification of the code snippets, and > with those the Docker compose files, in CI. > The overall idea is to parse the getting-started guide markdown and > let a workflow execute the code blocks for shell/bash. > I am not sure whether all guides can actually be verified, because > some of those Docker compose files start a couple of containers, which > can be a resource (RAM/CPU) issue in GitHub's hosted runners. > The alternatives would be: > - Never update the getting-started guides with the risk that those > become stale and outdated. > - Keep the manual verification process. > Any thoughts on this? > > Robert > > > [1] https://github.com/apache/polaris/tree/main/getting-started
