docs: rewrite the README against the standard provider template - #13
Merged
Conversation
The README led with developer commands and said little about what the provider is, what it can do, or how to install it. It also omitted the single most important fact about any provider: it is not standalone, and does nothing without an OpenEverest installation in the cluster. Rewritten against the shared template maintained in provider-sdk (internal/scaffold/_template/README.md), ordered by audience — platform users, operators, then contributors: what this is (with the architecture diagram), compatibility, a capability matrix using the same wording across all providers, Helm installation, usage, topologies, versions, configuration, development, and troubleshooting. Every table is filled from this repository's definition/ and chart metadata, so the versions, topologies, operator version and make targets now match reality. Signed-off-by: Diogo Recharte <diogo.recharte@solanica.io>
recharte
force-pushed
the
docs/standard-readme
branch
from
August 6, 2026 08:30
b22ad9c to
b7b1209
Compare
The rewritten README duplicated the dev-environment setup that dev/README.md already owns: prerequisites, the .env copy, and the raw tilt invocation. The two were free to drift. The README now states the requirement (a Kubernetes cluster), lists the make targets a contributor runs, and links to dev/README.md for the rest. dev/README.md gains the existing-cluster workflow and documents K8S_CONTEXT and DOCKER_REGISTRY_URL alongside the other .env settings. Signed-off-by: Diogo Recharte <diogo.recharte@solanica.io>
The README rewrite reduced the previous observability section to a single link, dropping the concrete steps: the kube-prometheus-stack install that uses deploy/observability/values-prometheus.yaml, the fact that KubeAI's PodMonitor comes from deploy/kubeai/values-gpu.yaml, and the Grafana dashboard shipped in examples/observability/. Restores those under Configuration as an Observability subsection, and brings back the two verification details the Usage section lost: checking the Model CR and its serving pods, and the chat/completions call showing that the model field is the Instance name. Signed-off-by: Diogo Recharte <diogo.recharte@solanica.io>
Nothing in the README told a reader that v2 and the providers are still moving under them. The compatibility table implies stability, so the only signal was what was missing. Adds a WARNING callout above the badges stating the consequence rather than the sentiment (schemas and chart values change in breaking ways, no upgrade path, not for production), plus a status badge so it stays visible once the callout scrolls off. Both carry a removal note so the sweep at v2 GA is one grep for "status-pre--alpha". Signed-off-by: Diogo Recharte <diogo.recharte@solanica.io>
Review feedback: "Version upgrades" read as though it might be about upgrading the provider, and the reader only worked out it meant the deployed version after reaching the Notes column. The ambiguity applies to the whole table, so it is fixed once above it rather than by renaming a row: the row names stay identical across providers, which is what makes the tables comparable. The upgrade row also names what is being upgraded. Signed-off-by: Diogo Recharte <diogo.recharte@solanica.io>
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
2 participants
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.
What
Rewrites
README.mdagainst the shared provider README template maintained in provider-sdk (see openeverest/provider-sdk#24).Why
The previous README mixed installation, cluster bootstrap runbooks, curl examples and Prometheus setup into one long Quick Start, with no statement of what the provider supports or that it does nothing without an OpenEverest installation in the cluster. The runbooks already live under
docs/; the README now links to them instead of inlining them.Structure
Ordered by audience — platform users, operators, then contributors:
Instance→ provider →Modelarchitecture diagram and a callout that the provider is not standaloneAccuracy
Tables are filled from
definition/: theautoscaledtopology with its four parameters, the three version bundles (includingollama-cpu), and theservercomponent's parameters (model.source,resourceProfile,cacheProfile,args,env).Because this provider serves models rather than storing data, the stateful capability rows (persistent storage, backups, PITR, restore) are deleted rather than filled with ❌ — per the template's guidance that rows which make no sense for a technology should be dropped.
The version and topology tables sit inside
<!-- BEGIN/END GENERATED -->markers, ready forprovider-sdk generateto fill them fromdefinition/in a follow-up.