experiments

package
v0.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package experiments is the registry of devcell's experimental features and the gate that turns them on.

An experiment is off until named in --experimental=a,b, DEVCELL_EXPERIMENTAL or [cell] experimental (the three are unioned). Code guards a feature with Set.Enabled or Require; docs are generated from List (see Markdown and JSON, wired into `task docs:experimental`). Names are "<group>-<slug>": the group is the area the experiment touches (ui, engine).

Lifecycle, after go-task's experiments package: an experiment is Active while it can be enabled; once shipped it becomes Released, once dropped Abandoned. Both stay registered so an old setting fails with a reason instead of an "unknown experiment" error.

Index

Constants

View Source 
const (
	BeginMarker = "<!-- experiments:begin -->"
	EndMarker   = "<!-- experiments:end -->"
)

Markers around the generated block in README.md and docs/experimental.md.

View Source 
const (
	Flag = "--experimental"       // comma-separated names
	Env  = "DEVCELL_EXPERIMENTAL" // comma-separated names
	Key  = "[cell] experimental"  // TOML list or comma-separated string
)

Where an experiment can be switched on.

Variables

View Source 
var (
	// Cage wraps the run in a host tmux session with a one-line bottom bar.
	Cage = Experiment{
		Name:    "ui-cage",
		Summary: "one-line bottom bar (workspace, cell name, clocks) drawn by a host tmux session around the agent",
		Doc:     "docs/cage.md",
		Ticket:  "CELL-655",
	}
	// BootPopup renders the boot panel in a tmux popup that closes before
	// the agent starts. Needs Cage.
	BootPopup = Experiment{
		Name:    "ui-boot-popup",
		Summary: "boot panel in a centred tmux popup, closed before the agent starts (needs ui-cage)",
		Doc:     "docs/cage.md",
		Ticket:  "CELL-657",
	}
	// Windows is the Windows guest: --os windows or winpe, engine winkit.
	Windows = Experiment{
		Name:    "engine-windows",
		Summary: "Windows guest (--os windows or winpe): a Windows PE + WSL VM run by the winkit engine on vz or QEMU",
		Doc:     "README.md#engines-and-guests",
	}
)

The registered experiments. Add a new one here and in all, then run `task docs:experimental`.

Functions

func Block 

func Block(doc string) (string, bool)

Block returns the text between the markers in doc.

func JSON 

func JSON() ([]byte, error)

JSON renders the registry for the website (web/src/data/experimental.json).

func Markdown 

func Markdown(linkBase string) string

Markdown renders the experiments table that README.md, docs/experimental.md and the website share. Doc links are prefixed with linkBase: "" for a file at the repo root, "../" from docs/, a GitHub blob URL for the site.

func Names 

func Names() []string

Names lists the names of the experiments that can be enabled.

func ReplaceBlock 

func ReplaceBlock(doc, body string) (string, error)

ReplaceBlock swaps the text between the markers in doc for body.

func Require 

func Require(s Set, x Experiment, what string) error

Require returns a *RequiredError naming what (e.g. "the windows guest") unless x is enabled in s. It is the one-line gate for a code path that needs an experiment.

Types

type Experiment 

type Experiment struct {
	Name    string // what users write: "<group>-<slug>", e.g. "ui-cage"
	Summary string // one line: what turning it on does
	Doc     string // repo-relative markdown path, e.g. "docs/cage.md"; "" when none
	Ticket  string // tracking ticket, e.g. "CELL-655"; "" when none
	State   State
}

Experiment describes one experimental feature.

func List 

func List() []Experiment

List returns every registered experiment, active or not.

func Lookup 

func Lookup(name string) (Experiment, bool)

Lookup finds the experiment named name.

func (Experiment) EnvSetting 

func (x Experiment) EnvSetting() string

EnvSetting is the environment form that enables x.

func (Experiment) Flag 

func (x Experiment) Flag() string

Flag is the command-line form that enables x.

func (Experiment) Group 

func (x Experiment) Group() string

Group is the area prefix of Name: "ui" for "ui-cage".

func (Experiment) HowToEnable 

func (x Experiment) HowToEnable() string

HowToEnable lists every way to turn x on, for error messages and docs.

func (Experiment) TOMLSetting 

func (x Experiment) TOMLSetting() string

TOMLSetting is the devcell.toml form that enables x.

type InactiveError 

type InactiveError struct{ Experiment }

InactiveError is a registered experiment that can no longer be enabled.

func (*InactiveError) Error 

func (e *InactiveError) Error() string

type RequiredError 

type RequiredError struct {
	What string // what was attempted, e.g. "the windows guest"
	Experiment
}

RequiredError is a code path reached without the experiment it needs.

func (*RequiredError) Error 

func (e *RequiredError) Error() string

type Set 

type Set map[string]bool

Set is the resolved set of enabled experiments.

func Resolve 

func Resolve(flagCSV string, configured []string) (Set, error)

Resolve unions the --experimental flag value (comma-separated) with the names the config resolved from [cell] experimental and DEVCELL_EXPERIMENTAL (cfg.CellSection.ResolvedExperimental; the environment is read there, like every other devcell option). Unknown names are an *UnknownError, inactive ones an *InactiveError, so a typo or a stale setting cannot silently leave a feature off.

func (Set) Enabled 

func (s Set) Enabled(x Experiment) bool

Enabled reports whether x is on.

type State 

type State int

State is where an experiment is in its lifecycle. 

const (
	Active    State = iota // can be enabled
	Released               // shipped: always on, the setting is a no-op error
	Abandoned              // dropped: cannot be enabled
)

func (State) String 

func (s State) String() string

String is the lower-case state name used in JSON and docs.

type UnknownError 

type UnknownError struct {
	Source string // Flag, Env or Key
	Name   string
}

UnknownError is a name that is not a registered experiment.

func (*UnknownError) Error 

func (e *UnknownError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.