Specs

Each spec in this directory states a current product requirement of the Operator. For when to write or update one, see Development workflow.

Areas

A spec belongs to an area. An area is a subdirectory of this one, named after the part of the Operator the capability lives in. A capability not tied to one area sits at the top level of doc/specs/.

Area	Capabilities it holds
`bridge/`	The v2alpha1 resources, their reconcilers, and the bridge API and web UI.

Add an area when a capability fits none of the existing ones, and list it in this table.

Spec rules

State what the Operator does and why. Leave out implementation details, directions, and technical choices. Those belong in an ADR.
Keep the spec short enough for a developer who knows the project to read in a few minutes. Aim for about 30 lines before the FAQ. It is a target, not a limit: a capability with more observable behaviors than that needs more requirements, not shorter ones. Move the reasoning to the FAQ rather than dropping a requirement to fit.
Write each requirement as behavior that a test can observe.
State what the Operator does, not what it no longer does. Put a removed capability under Out of scope, so no requirement asks for a test that it stays removed.
Split a large capability into a parent spec and child specs. The parent links each child, and each child links the parent.
Set Status to Proposed while the capability is being built, and to Implemented in the merge request that delivers the last requirement. A spec that describes what the Operator does today is Implemented.

Spec format

Put the file in its area directory, and name it after the capability, in snake_case.md. For a capability with child specs, create a directory inside the area and make the parent spec its _index.md.

markdown
---
stage: GitLab Delivery
group: Operate
info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments>
title: <Capability>
---

Status: Proposed
Issue: <issue link>
Parent: <parent spec link, or none>

## Goal

<Who needs what, and why. One or two sentences.>

## Requirements

- <One observable behavior per line.>

## Out of scope

- <What this spec does not cover.>

## FAQ

- **<Question asked while refining the spec.>** <Answer.>

Was this page helpful?