Rongsong Shen
be9a03a3e9
Requirements: 6 requirement areas covering single build path, unit/ backend/integration test migration, binary discovery, and doc consistency. Design: 6 rounds of independent adversarial review to convergence (2 real technical bugs caught -- unresolved Meson placeholder tokens in CGO flags, invalid unquoted dict-literal keys -- plus a long tail of stale Makefile references across docs/scripts/ source comments, closed by a scope-rule restructure rather than continued line-by-line patching). Tasks: 4 major / 12 sub-tasks, task-graph sanity review passed after one repair round. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XYdtrEWWZfKRRGED7raEYg
63 lines
7.6 KiB
Markdown
63 lines
7.6 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
`src/frontend/Makefile` and Meson's `tools/go_build` wrapper are two independent, parallel build orchestration paths for the same two Go binaries (apiserver, xcecli), each independently computing the same version-fingerprint logic (`commit_id`/`build_time`/`dirty_fingerprint`). This duplication has already caused a real defect (a shell exit-status bug in the Makefile's independent fingerprint computation, `dirty-content-fingerprint` task 4.3) and the Makefile's own `build-server` target is independently confirmed currently broken (bug-1597) — the project's own documentation already tells developers to avoid it in favor of `/xce-build apiserver`.
|
|
|
|
This feature removes `src/frontend/Makefile` entirely and consolidates all apiserver/xcecli build and test execution onto Meson, so exactly one build system exists for these components going forward. This is a confirmed decision, not an option to weigh during design: Meson is retained, the Makefile is deleted outright, not kept as a thin or compatibility wrapper.
|
|
|
|
## Boundary Context
|
|
|
|
- **In scope**: removing `src/frontend/Makefile`; ensuring apiserver/xcecli builds, unit tests, CGO-backed backend tests, and the integration/regression test suite are all runnable through Meson or direct, documented, Makefile-free invocations; updating any project script or documentation that discovers a built binary via a Makefile-specific fixed path or instructs a developer to run a Makefile target.
|
|
- **Out of scope**: changing the underlying version-fingerprint computation itself (the single surviving source of truth is unchanged, only the duplicate second computation is removed); changing the CGO build-flag derivation Meson's apiserver build already performs (this feature reuses it, it does not redesign it); rewriting historical/frozen spec documents (e.g. `tasks.md`/`research.md`/`design.md` of already-completed specs) that reference Makefile targets as acceptance criteria for work already shipped; fixing unrelated, adjacent build-tooling defects noted during investigation (e.g. `component-failover-adoption`'s `set -euo pipefail` CGO-test-skip issue).
|
|
- **Adjacent expectations**: this feature depends on Meson's existing apiserver build already deriving correct CGO flags — that derivation is reused, not duplicated, for backend test execution. Downstream scripts that discover apiserver/xcecli binaries (e.g. HA deploy scripts, resource-verification scripts) must continue to find a usable binary after this change; none of them may be left depending on a Makefile-specific fixed output path once the Makefile is gone.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: Single Build Path for Go Binaries
|
|
**Objective:** As a developer, I want apiserver and xcecli to be built through exactly one system, so that build logic and version-fingerprint computation cannot silently drift out of sync between two independent implementations.
|
|
|
|
#### Acceptance Criteria
|
|
1. When a developer builds apiserver or xcecli through the project's canonical build tooling, the system shall produce the binary without invoking any `src/frontend/Makefile` target.
|
|
2. The system shall compute each binary's version-fingerprint information (commit id, build time, dirty-content fingerprint) from exactly one implementation, not from two independently maintained computations.
|
|
3. The system shall not include a `src/frontend/Makefile` file once the build, unit-test, backend-test, and integration-test capabilities described in Requirements 1-4 are all available without it.
|
|
|
|
### Requirement 2: Go Unit Test Execution Without the Makefile
|
|
**Objective:** As a developer, I want apiserver/xcecli unit tests runnable without `src/frontend/Makefile`, so that test execution is not split across two orchestration systems.
|
|
|
|
#### Acceptance Criteria
|
|
1. When the project's canonical build tooling runs apiserver or xcecli unit tests, the system shall do so without invoking `src/frontend/Makefile`'s `test` target.
|
|
2. The system shall preserve existing unit-test behavior (no external dependencies, no live server required) after this change.
|
|
3. If a unit test fails, then the system shall report the failure in a form at least as clear and actionable as the current Makefile-driven output (test name, failure reason).
|
|
|
|
### Requirement 3: CGO-Backed Backend Test Coverage Preserved
|
|
**Objective:** As a developer, I want the CGO-backed backend test suite runnable without `src/frontend/Makefile`, so that removing the Makefile does not silently drop test coverage.
|
|
|
|
#### Acceptance Criteria
|
|
1. The system shall provide a way to run the full CGO-backed backend test suite that does not depend on `src/frontend/Makefile`.
|
|
2. When the CGO-backed backend test suite runs, the system shall derive its CGO build flags from the same single source Meson's apiserver build already uses, not from a second, independently maintained derivation.
|
|
3. The system shall not reduce CGO-backed backend test coverage at any point during this migration — an equivalent, Makefile-free way to run this suite shall exist before `src/frontend/Makefile`'s `test-backend` target is removed.
|
|
|
|
### Requirement 4: Integration/Regression Test Suite Targets a Canonical Build
|
|
**Objective:** As a developer, I want to run the apiserver integration/regression test suite against a binary built by the project's canonical tooling, so that verification does not require a Makefile-built artifact.
|
|
|
|
#### Acceptance Criteria
|
|
1. When a developer runs the integration/regression test suite, the system shall accept a binary built by the project's canonical (Makefile-free) build tooling as the target under test.
|
|
2. The system shall not require `src/frontend/Makefile`'s `build-cli` or `build-server` targets to produce the binary under test.
|
|
3. The system shall preserve the existing regression suite's scope and pass/fail criteria after this change.
|
|
|
|
### Requirement 5: Binary Discovery Independent of Makefile-Specific Paths
|
|
**Objective:** As an operator or script maintainer, I want project scripts that locate a built apiserver or xcecli binary to do so without depending on a Makefile-specific fixed output path, so that removing the Makefile does not break deployment or verification tooling.
|
|
|
|
#### Acceptance Criteria
|
|
1. When a project script needs to locate a built apiserver or xcecli binary, the system shall discover it from the canonical build tooling's output location as the primary source.
|
|
2. If no binary is found at the canonical build tooling's output location, then the system shall report an error or warning that names the canonical (Makefile-free) build command to run, and shall not instruct the operator to run a `src/frontend/Makefile` target that no longer exists.
|
|
3. The system shall not require any project script to depend on a `src/frontend/Makefile`-specific fixed output path (e.g. `/tmp/apiserver`, `/tmp/xce_static`) as its only means of locating a built binary.
|
|
|
|
### Requirement 6: Documentation Reflects a Single Build System
|
|
**Objective:** As a developer or operator reading project documentation, I want build and test instructions to reference only the surviving build system, so that I am never directed to run a target that no longer exists.
|
|
|
|
#### Acceptance Criteria
|
|
1. When live (non-historical) project documentation describes how to build or test apiserver/xcecli, the system's documentation shall reference only the canonical Makefile-free build/test commands.
|
|
2. The system shall not retain any live documentation instructing a developer to run a `src/frontend/Makefile` target.
|
|
3. Where a historical, already-completed spec document references a Makefile target as a frozen record of past acceptance criteria, the system shall leave that document unchanged — this requirement applies only to live, currently-authoritative documentation.
|