Hi Robert, 1. This is a great idea. Are you proposing to move the README files to the website directly? I would prefer to link them if possible, so we can expose them on the website while keeping the files in the getting-started folder.
2. This is also a very good point. I have seen many projects with outdated or non-functional README files. If we can verify that the instructions are actually working through CI, that would be a significant improvement. Regards, JB 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 >
