docs: remove experimental-gating design doc · Entire

docs: remove experimental-gating design doc

1229f6c→main·

gtrrz-victor·3d ago·1 file·+0 added/-180 removed

The design doc lived under a gitignored path and was only force-added; drop it from the PR. Behavior is documented in CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com

Experimental Command Gating — Design

Date: 2026-07-10
Branch: experimental-command-gating

Problem

A curated set of maturing/hidden commands should be visible to developers (any non-release build: go build, go run, mise) and hidden in shipped binaries (any GoReleaser build, prod and nonprod). They should also be grouped under an "Experimental commands:" section in entire help when visible, instead of being scattered as unrelated hidden commands.

This replaces the current hardcoded Hidden: true on these commands with a single build-time gate.

Scope

Gated as experimental (10 commands)

Root-level (join root's "Experimental commands:" help group):

Sub-command (joins an experimental group under checkpoint):

Explicitly out of scope (untouched, stay always-hidden)

These are hidden for reasons other than "experimental" and must keep working in release binaries:

Note: entire search (root shortcut) is gated; the canonical checkpoint search is not hidden and is left untouched. The canonical checkpoint search in checkpoint_group.go stays a normal AddCommand.

Design

Gate mechanism

New package cmd/entire/cli/experimental/experimental.go, mirroring the versioninfo ldflags precedent (default value is dev-friendly; only GoReleaser stamps a non-default):

package experimental

import "github.com/spf13/cobra"

// Visible controls whether experimental commands are shown in help. It is
// stamped by GoReleaser via ldflags
// (-X github.com/entireio/cli/cmd/entire/cli/experimental.Visible=false)
// to hide them in shipped binaries. It defaults to "true", so every
// non-release build (go build, go run, mise) shows them. The commands remain
// experimental and fully runnable regardless of this flag — it only toggles
// visibility.
var Visible = "true"

// IsVisible reports whether experimental commands are shown in help.
func IsVisible() bool { return Visible != "false" }

// GroupID is the cobra group experimental commands are filed under.
const GroupID = "experimental"

const groupTitle = "Experimental commands:";

// Register adds child under parent, gated and grouped as experimental.
// It overrides any Hidden value the child's constructor set, so callers do not
// need to touch the constructors (including ones in other packages).
func Register(parent, child *cobra.Command) {
    if !parent.ContainsGroup(GroupID) {
        parent.AddGroup(&cobra.Group{ID: GroupID, Title: groupTitle})
    }
    child.Hidden = !IsVisible()
    child.GroupID = GroupID
    parent.AddCommand(child)
}

Rationale for Register(parent, child) overriding Hidden: the two experimental commands in other packages (review, investigate) set Hidden: true internally. Overriding at the registration site means we do not edit those packages and there is a single source of truth for the gate.

The cobra group is registered (and GroupID set) only when experimental commands are visible. In release builds the children are simply marked Hidden with no GroupID. This is deliberate: registering an always-empty group would make cobra relabel every other root command under its "Additional Commands:" header (cobra puts ungrouped commands there whenever any group exists), changing release help for no reason. Leaving GroupID empty also means cobra never references an unregistered group, so it cannot panic.

Wiring

Swap AddCommand → experimental.Register at exactly these sites:

No changes to the command constructors themselves. Inline Hidden: true in the constructors is harmless (overridden by Register) but may be left as-is to keep the diff focused on registration sites.

Build gating

Stable releases and nightly builds run through the same .goreleaser.yaml (via release.yml); they differ only by git tag — stable is vX.Y.Z, nightly is vX.Y.Z-nightly.* (a prerelease). Local builds carry no ldflags at all.

Build Tag .Prerelease Stamp Result
Local (go build/go run/mise) — — none (default) visible
Nightly vX.Y.Z-nightly.* non-empty Visible=true visible
Stable vX.Y.Z empty Visible=false hidden

The entire build's ldflags in .goreleaser.yaml gets a GoReleaser template that keys off .Prerelease:

-X github.com/entireio/cli/cmd/entire/cli/experimental.Visible={{ if .Prerelease }}true{{ else }}false{{ end }}

.goreleaser.nonprod.yaml is not stamped: it builds only the git-remote-entire helper, never the entire binary, so there is nothing to gate there.

mise convenience task

Add a plain build task (no experimental ldflags, so experimental stays visible):

[tasks.build]
run = "CGO_ENABLED=0 go build -o entire ./cmd/entire/"

This is ergonomic only; any non-GoReleaser build already defaults to visible.

Testing

Non-goals