v1.0.0: stabilize CRD + graduate to stable (reframed from v0.1.0)

[viniciusdc]

Status (2026-08-14): v0.1.0 shipped as the first EffVer release, graduating off the alpha line. The EffVer adoption + maintainer-doc slice is done (#178, ADR-003). This tracker now targets v1.0.0 - the CRD-stabilization and hardening milestone; see the scope-change comment below for the rationale. Checked items are complete; unchecked items gate v1.0.0.

Goal

Stabilize the CRD and graduate the operator to a stable v1.0.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

Done - shipped in #178 (ADR-003). Kept here for reference.

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 mentioned "semantic versioning" - now updated to EffVer in #178:

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

Documentation readiness for v1.0.0

Top-level

• README.md - softened "may change without notice" into a concrete EffVer statement (docs: adopt Effort-based Versioning (EffVer) #178).
• 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 (docs: adopt Effort-based Versioning (EffVer) #178).
• release-checklist.md - EffVer language (docs: adopt Effort-based Versioning (EffVer) #178). Still open: 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 (docs: adopt Effort-based Versioning (EffVer) #178).

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 v1.0.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 v1.0.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-v1.0.0 - especially field removals. After v1.0.0, CRD shape changes become MACRO bumps and real migration work for consumers. (Pre-1.0, on the 0.x line, CRD changes still ship but are signposted MESO/MACRO-in-0.x bumps.)

Gating set for v1.0.0 (must close before the stable 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-v1.0.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) - shipped in v0.1.0
• [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 stability-critical of all; if it lands after a public 0.x, signpost it as a breaking 0.x bump)

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

• v1.0.0: stabilize CRD + graduate to stable (reframed from v0.1.0) #129 - this issue (EffVer adoption, doc audit, examples, release-process cleanup)

v1.0.0 is a real milestone: the point where the CRD is settled and consumers can depend on it.

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. Resolved: landed as Add nebari-app library Helm chart for NebariApp CR #150 and shipped in v0.1.0 (charts/nebari-app).

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: "v1.0.0 Release" - meta-epic, formal GitHub Milestone, attach the remaining gating items + this issue. Sub-items: doc work above, gating bugs, CRD-spec changes, release validation. Closes when v1.0.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 v1.0.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 (v1.0.0: stabilize CRD + graduate to stable (reframed from v0.1.0) #129) finishes last - maintainer docs reflect the final shape.

Cut v1.0.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:

• docs/maintainers/release-checklist.md job-name list. (Still open.)
• EffVer language across all three docs/maintainers/*.md (docs: adopt Effort-based Versioning (EffVer) #178).
• A short "what changed since alpha.20" section - done in the v0.1.0 release notes, leading with the EffVer adoption.

Out-of-repo follow-up (doesn't gate v1.0.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 v1.0.0)

• Versioning policy: EffVer documented across all three maintainer docs; README's "may change without notice" softened (docs: adopt Effort-based Versioning (EffVer) #178, ADR-003).
• 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: the v0.1.0 cut exercised the full pipeline (five jobs) and the first nebari-app chart publish end-to-end.
• Cut v1.0.0.

When to formalize as a GitHub Milestone

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

[viniciusdc]

EffVer adoption landed in #178. Checking off the versioning slice of this tracker:

• Versioning policy: EffVer documented across all three maintainer docs (release-process.md, release-setup.md, release-checklist.md) - SemVer framing replaced with the MACRO/MESO/MICRO effort rubric, references repointed at the EffVer spec.
• README "may change without notice" softened into a concrete EffVer statement (pre-1.0, watch the MACRO digit for manifest-affecting upgrades).
• Alpha/beta pre-release ladder retired; -rc.N kept for dry runs.
• Decision recorded as ADR-003 (docs/decisions/2026-08-14-adopt-effver.md) with the rubric, rationale, and alternatives (SemVer, CalVer).

Still open in this section, deliberately left out of #178 to keep it scoped:

• release-checklist.md job-name list (lines ~84-90) still lists the wrong jobs - should be the five actual release.yml jobs (tests, build-manifests, goreleaser, publish-helm-chart, sync-helm-repository). Belongs in the release-process cleanup pass.
• CHANGELOG decision (curated vs GitHub-generated notes) - not addressed.

No tag was cut - the v0.1.0 graduation stays gated by the rest of this checklist.

[viniciusdc]

Scope change: this tracker now targets v1.0.0 (was v0.1.0)

Reframing per the EffVer adoption (ADR-003, landed in #178).

Under EffVer the leading 0. already means "pre-stable - the CRD can still change between releases." So the CRD-settling and hardening work in this issue belongs to the stability milestone, which under EffVer is v1.0.0 (where "effort semantics become trustworthy"), not to graduating off the alpha line. Graduating off alpha is just "start the EffVer 0.x line," and that can happen now.

What this means concretely:

• v0.1.0 is cut separately, now - the first EffVer release of what is already on main: the nebari-app library chart (Add nebari-app library Helm chart for NebariApp CR #150), dark/light icons (add configuration for dark and light icons #131), auth issuer hardening (docs(auth): SecurityPolicy issuer stays in-cluster — investigation result for #112, with tests #144), and the EffVer docs (docs: adopt Effort-based Versioning (EffVer) #178). It promises no CRD stability, and that is expected under 0.x.
• The gating set below now targets v1.0.0. Read every "v0.1.0" in the body above as "v1.0.0". The CRD-spec items - especially the field removal feat: remove ForwardAccessToken, add app-level OIDC redirect URIs #61 - still want to land before v1.0.0 to avoid post-stable migration work, and the field-removal-first ordering is unchanged.
• The "anything that touches the CRD spec lands pre-v0.1.0" rule now reads "pre-v1.0.0."
• Already done: the versioning-policy + maintainer-doc slice (EffVer across the three release docs, README softened, ADR-003) landed in docs: adopt Effort-based Versioning (EffVer) #178.

No gating issue is dropped - only the target version changes. Net effect: users get the chart + fixes now on 0.1.0, and v1.0.0 becomes the honest "CRD is settled, safe to depend on" line.