v0.1.0: graduate from alpha, adopt EffVer, audit docs + release process

[viniciusdc]

Goal

Graduate the operator from alpha to its first non-alpha cut, v0.1.0. This issue tracks everything that needs to land — and everything we want to audit — before that release.

Current state: v0.1.0-alpha.20 (cut 2026-05-20). Twenty alphas, chart-image fix from #128 landed cleanly, Node 24 audit done. The MVP milestone "Operator: Architecture + CRDs + Decisions + MVP" is closed. Time to draw the line and call the next cut "real."

Not a feature freeze — a quality bar. Docs match the code, examples actually run, release process is reproducible without tribal knowledge.

Versioning: adopt EffVer

Going forward (starting with v0.1.0), use Effort-based Versioning (EffVer) — MACRO.MESO.MICRO — instead of strict SemVer.

EffVer component	Meaning for a NebariApp consumer / pack author
MACRO (X.y.z)	"Expect significant changes." CRD shape moved meaningfully, you'll touch your pack manifests.
MESO (x.Y.z)	"Could break, watch for warnings." New fields, optional opt-ins, deprecations.
MICRO (x.y.Z)	"Should be safe." Bug fixes, doc updates, operator-internal refactors with no CRD impact.

Why EffVer over SemVer:

• SemVer demands backwards-compat precision we don't have yet. Pre-1.0 we already break things on minor bumps; SemVer says that warrants a major. EffVer just says "watch the MACRO digit for migration work."
• Maps cleanly to what pack authors care about: "do I need to read release notes or can I just bump."
• Honest signal during pre-stable.

Tag format stays vX.Y.Z (Helm chart + GitHub Releases want SemVer-shaped tags). Interpretation in docs changes.

Maintainer docs that mention "semantic versioning" need updating:

• docs/maintainers/release-process.md
• docs/maintainers/release-setup.md
• docs/maintainers/release-checklist.md

Documentation readiness for v0.1.0

Top-level

• README.md — soften "may change without notice" language (still pre-1.0, but the strong wording should go).
• CONTRIBUTING.md — review against current PR / branch / lint workflow.
• Decide: curated CHANGELOG.md, or rely solely on GitHub-generated release notes.

User-facing docs (docs/)

• docs/quickstart.md — verify steps still match dev/Makefile. Cover the user-provided-TLS path and the new chart manager.image.* defaults.
• docs/configuration-reference.md — audit for every CRD field added since 2026-03: routing.tls.secretName, auth.forwardAccessToken, auth.denyRedirect, auth.tokenExchange, auth.spaClient, auth.deviceFlowClient, plus whatever lands from the gating set (multi-port, dark/light icons, etc.).
• docs/troubleshooting.md — sanity-check the symptom list against currently surfaced condition reasons.
• docs/api-reference.md — auto-generated via make docs; verify it generates clean from main HEAD.
• docs/reconcilers/{README,routing,validation,authentication}.md — match current responsibilities. TLS reconciler probably wants its own doc.
• docs/makefile-reference.md — verify coverage of new/changed targets (generate-dev, helm-chart-version semantics).

Maintainer docs (docs/maintainers/)

• release-process.md — EffVer language.
• release-checklist.md — EffVer language. Also: job-name list (lines 84-90) is wrong vs current release.yml. Five jobs (tests, build-manifests, goreleaser, publish-helm-chart, sync-helm-repository), not seven.
• release-setup.md — EffVer language.

Design / decision / plan archives

• Verify nothing in docs/plans/ is an orphan (never landed, never decisioned).

Examples

Currently dev/examples/ has just two files. For v0.1.0:

• Minimal NebariApp (sanity-check end-to-end against make setup).
• NebariApp with auth.enabled: true + Keycloak provisioning.
• NebariApp with routing.tls.secretName (user-provided cert).
• NebariApp with routing.publicRoutes for health endpoints.
• NebariApp with routing.routes[].port (multi-port — gated on feat(api): per-route port overrides on NebariApp routes #121).
• A non-routing NebariApp (operator-as-contract-aggregator mode).

Each example: kubectl apply -f-able against the dev cluster, with an inline comment explaining what it demonstrates.

Automated documentation: what we have, what to expand

Today: docs/api-reference.md auto-generated from api/v1/ via crd-ref-docs (make docs).

Add at least one of these before v0.1.0:

• Condition / event reason table from the EventReason* / Reason* constants in api/v1/nebariapp_types.go. Lowest-friction starting point.
• RBAC summary table from // +kubebuilder:rbac: markers.
• Helm values reference (e.g. via helm-docs).
• Naming-rules diagram from naming.ValidateResourceNames so pack authors see name-length implications early.

Goal: a new pack author shouldn't have to read the operator source to understand what their NebariApp produces.

Triage

Rule: anything that touches the CRD spec lands pre-v0.1.0 — especially field removals. After v0.1.0, CRD shape changes become MACRO bumps and real migration work for consumers.

Gating set for v0.1.0 (must close before the cut)

Bugs / security

• NebariApp: publicRoutes + default enforceAtGateway produces two competing HTTPRoutes for the same path #118 — publicRoutes + default enforceAtGateway produces two competing HTTPRoutes (contract bug)
• security: Restrict Keycloak OIDC client WebOrigins from wildcard to specific hostnames #37 — OIDC client WebOrigins wildcard → specific hostnames (security)
• Handle concurrent realm scope creation in syncClientScopes #45 — concurrent realm scope race (auth bug)
• syncClientScopes should remove scopes no longer in Spec.Auth.Scopes #44 — syncClientScopes doesn't remove scopes no longer in spec (drift bug)

CRD-spec changes (must land pre-v0.1.0)

• feat(api): per-route port overrides on NebariApp routes #121 + docs(design): multi-port routes and streaming for NebariApp #120 — multi-port routes (RouteMatch.port — additive)
• add configuration for dark and light icons #131 — dark/light icons on LandingPage (additive)
• [ENH] - Expose running child resources via NebariApp status.serviceDiscovery.children #117 — status.serviceDiscovery.children (status shape change)
• Add Keycloak client-role support to NebariApp.auth.keycloakConfig #119 — Keycloak client-role support (auth.keycloakConfig additions)
• Make hostname optional in NebariApp, add subdomain field #69 — hostname optional + subdomain field (changes required-field semantics)
• feat: remove ForwardAccessToken, add app-level OIDC redirect URIs #61 — remove forwardAccessToken, add app-level OIDC redirect URIs (field removal — the most v0.1.0-critical of all)

Auth quality

• fix(auth/keycloak): enable Standard Token Exchange v2 on peer clients #116 — Standard Token Exchange v2 on peer clients

Release readiness

• Pre-v0.1.0 release validation pass #132 — Pre-v0.1.0 release validation pass (runs after the rest of the gating set lands on main).

Doc / process

• v0.1.0: graduate from alpha, adopt EffVer, audit docs + release process #129 — this issue (EffVer adoption, doc audit, examples, release-process cleanup)

That's 14 items + this tracker. v0.1.0 is a real milestone, not a renamed alpha.

Worth landing if cheap (no CRD touch)

• Watch user-provided TLS secrets to fast-track TLSReady transitions #115 — Watch user-provided TLS secrets (perf optimization, internal)
• enhancement: Replace unconditional 1-minute requeue with event-driven reconciliation #35 + enhancement: Add watches on owned resources (HTTPRoute, SecurityPolicy, Secret) #30 — Event-driven reconciliation + watches on owned resources (pair — quality, internal)

Decision point

• Proposal: ship a Helm library chart exporting NebariApp templates for use across packs #130 — Helm library chart for NebariApp templates. Doesn't touch the operator's own CRD, so the new rule doesn't auto-promote it. Landing pre-v0.1.0 saves a coordinated pack-side refactor in v0.2.0; deferring is fine if the v0.1.0 set is already big enough.

Punt to v0.1.x patches (MICRO under EffVer, no CRD shape change)

• [MAINT] - Check if Keycloak redirection and access is still working when running operator locally #84 — Keycloak local redirection maintenance check
• Add reconciler test asserting SecurityPolicy.spec.oidc.provider has Token on in-cluster URL and Authorization on public URL #113 — Reconciler test for SecurityPolicy.spec.oidc.provider
• enhancement: Add test coverage for Keycloak integration and main Reconcile method #38 — Keycloak + main Reconcile test coverage
• cleanup: Remove dead code - unused LoadConfig() and duplicate LoadKeycloakCredentials() #34 — Dead code removal
• enhancement: Log warning on invalid environment variable values #36 — Log warning on invalid env vars
• enhancement: Initialize all sub-reconcilers consistently in main.go #33 — Consistent sub-reconciler initialization

Punt to v0.2.0+ (no CRD touch but larger scope / epic-level)

• [Architecture] - Service Discovery API — Using NebariApp CRDs as a Kubernetes-Native Service Registry #54 — Service Discovery API architecture (epic-level, ongoing design)
• OIDC SecurityPolicy.Issuer field stays on in-cluster URL; investigate iss-claim mismatch with Keycloak frontendUrl deployments #112 — OIDC SecurityPolicy.Issuer investigation (diagnostic, may be no-op)

Tracking epics

The existing epics (#78 CRD evolution, #79 Keycloak & Auth, #80 Reconciler & Tech Debt) cover most child issues already, and a final one:

• Epic: "v0.1.0 Release" — meta-epic, formal GitHub Milestone, attach all 14 gating items + this issue. Sub-items: doc work above, gating bugs, CRD-spec changes, release validation. Closes when v0.1.0 ships.

Ordering recommendation (within the gating set)

#132 (release validation) explicitly depends on the rest of the gating set being on main. Suggested order:

1. Field-removal first: feat: remove ForwardAccessToken, add app-level OIDC redirect URIs #61 — every other v0.1.0 commit shapes around the final CRD. Settling it early lowers churn.
2. Additive CRD changes (independent, any order): feat(api): per-route port overrides on NebariApp routes #121/docs(design): multi-port routes and streaming for NebariApp #120, add configuration for dark and light icons #131, [ENH] - Expose running child resources via NebariApp status.serviceDiscovery.children #117, Add Keycloak client-role support to NebariApp.auth.keycloakConfig #119, Make hostname optional in NebariApp, add subdomain field #69.
3. Bugs / auth quality (parallel with 2): NebariApp: publicRoutes + default enforceAtGateway produces two competing HTTPRoutes for the same path #118, security: Restrict Keycloak OIDC client WebOrigins from wildcard to specific hostnames #37, Handle concurrent realm scope creation in syncClientScopes #45, syncClientScopes should remove scopes no longer in Spec.Auth.Scopes #44, fix(auth/keycloak): enable Standard Token Exchange v2 on peer clients #116.
4. Release validation: Pre-v0.1.0 release validation pass #132 once 1–3 are merged.
5. Doc / process cleanup: this issue (v0.1.0: graduate from alpha, adopt EffVer, audit docs + release process #129) finishes last — maintainer docs reflect the final shape.

Cut v0.1.0 when this issue's "Done when" checklist is fully ticked.

Release process audit

Verified end-to-end via v0.1.0-alpha.20:

• ✅ Tests → manifests → goreleaser → helm chart → helm-repo sync. Five jobs, all green.
• ✅ Chart values.yaml correctly stamped with registry-qualified image + version tag (ci(release): pass IMG to make helm-chart so values.yaml inherits the pinned image #128).
• ✅ Node 24 deprecation warnings cleared from this repo's workflows (ci(build-pr): bump azure/setup-helm to v5 and actions/github-script to v9 #125, ci(release): bump docker/setup-qemu-action to v4 and softprops/action-gh-release to v3 #126).

Stale items to fix before v0.1.0:

• docs/maintainers/release-checklist.md job-name list.
• EffVer language across all three docs/maintainers/*.md.
• A short "what changed since alpha.20" section in v0.1.0's release notes pointing at the EffVer adoption.

Out-of-repo follow-up (doesn't gate v0.1.0):

• ci: upgrade GitHub Actions to Node 24 (Node 20 runtime deprecation) helm-repository#39 — Node 24 upgrades for sync-chart composite action.

Done when (acceptance criteria for v0.1.0)

• Versioning policy: EffVer documented across all three maintainer docs; README's "may change without notice" softened.
• All gating issues above closed.
• Docs checklist above all checked.
• Examples checklist above all checked.
• At least one automated-doc addition from the list above.
• docs/maintainers/release-checklist.md job-name list matches actual release.yml.
• Dry-run release: cut one more alpha (or v0.1.0-rc.1) and verify the checklist completes top-to-bottom with no manual recovery.
• Cut v0.1.0.

When to formalize as a GitHub Milestone

Once triage above is locked, create the v0.1.0 Milestone in GitHub and attach the gating issues. Holding off until then to avoid premature attachment.