a6 GA Readiness

[shreemaan-abhishek]

Goal

Make a6 stable enough for GA. Scope is the imperative + declarative APISIX CLI defined in PRD.md, the 40 bundled skills under skills/, and the supporting docs / release pipeline. Excludes any new feature work beyond what's already merged on main.

Context

We are mirroring the GA-readiness approach used for the sibling project api7/a7 (issue #22), which has a documented phased test plan (docs/ga-test-plan.md) and execution log (docs/ga-test-report.md) that we can lift wholesale.

The pre-existing tracking issue #14 (test / skills / docs review findings) covers a subset of the work below. Its 2026-04-28 boundary correction is authoritative: automated E2E validates CLI -> real Admin API -> CLI read-back, not the real proxy / data-plane chain.

Current state snapshot (2026-05-26):

• No git tags, no GitHub Releases, no CHANGELOG, no release workflow, no .goreleaser.yml. (a7 has the goreleaser config but is also missing the workflow and tags; a6 can copy and adapt it. Tracked for a7 in Wire .goreleaser.yml to a release workflow and cut the first tag a7#53.)
• E2E CI runs against a single APISIX image (apache/apisix:3.15.0-debian) on a single OS (ubuntu-latest).
• Test coverage ~52.4%; named thin spots in Follow-up: a6 test / skills / docs review findings #14 P1 / P2: pkg/selector, pkg/tableprinter, pkg/cmd/root, pkg/cmd/config/configutil.
• 11 Skip(...) call sites in test/e2e/ masking real product gaps.
• Self-update (a6 update, internal/update/) has no upstream artifacts to update from.

Sub-issues

Work is broken down into the linked sub-issues below. Each one self-declares "Part of #33" in its body.

1. GA scope statement and supported-version matrix (Define a6 GA scope and supported-version matrix #49). Write down what is in and out of GA, supported APISIX versions (proposal: 3.2 LTS, 3.9, 3.15), supported OS / arch, and which features are "stable" vs "experimental". Land as docs/ga-scope.md and reconcile against PRD.md and docs/roadmap.md (the roadmap summary table is currently stale: it shows skills PRs as 🚧/⬚ even though they merged in March via PRs feat(skills): add skills infrastructure and shared skill #1 to feat(skills): add advanced recipes and persona skills #9).

2. Manual smoke validation against a live APISIX (Run manual smoke validation of a6 CLI against a live APISIX #34). Build the a6 binary from main, point it at a real APISIX deployment (proposal: a local docker-compose with APISIX 3.15 + etcd, plus at least one run each against 3.2 LTS and 3.9 for the matrix), and run the phased CLI walkthrough by hand. For each of 14 resources: create / get (all output formats) / list / update / delete / verify cleanup. Plus declarative config dump / diff / sync / validate. This walkthrough is where real-traffic verification lives (route forwarding, multi-node upstreams, key-auth flow, etc.) per Follow-up: a6 test / skills / docs review findings #14's earlier semantic cases. Capture every observation in docs/ga-test-report.md with pass / fail / bug columns. Each bug found gets a failing test added first, then a fix (a7 protocol). Re-run after fixes as Run 2 regression. Primary source of bug-discovery for GA.

3. Phased automated E2E parity for the same surface (Land docs/ga-test-plan.md and achieve automated E2E parity with the manual pass #35). Land docs/ga-test-plan.md modelled on a7's plan. Ensure every scenario walked manually in Run manual smoke validation of a6 CLI against a live APISIX #34 has a corresponding Ginkgo test in test/e2e/, staying within Follow-up: a6 test / skills / docs review findings #14's 2026-04-28 boundary: CLI -> real Admin API -> CLI read-back, not real proxy traffic. Where the manual pass exposed an automated gap, add the test.

4. Eliminate silent test skips (Eliminate silent test skips in test/e2e/ #36). Audit all 11 Skip(...) sites in test/e2e/. For each: make it pass, gate on a documented environment flag, or remove the feature. Specific known cases: skywalking (already landed via PR test: enable skywalking plugin in e2e apisix #32 / closes Follow-up: a6 test / skills / docs review findings #14 P0), ai-content-moderation, stream-mode ssl-stream-route, global-rule labels, debug-logs auto-detect.

5. Release engineering (Wire goreleaser, cut v0.1.0-rc1, and verify a6 update end-to-end #37). Port a7's .goreleaser.yml to a6 (substitute project name and module path). Add .github/workflows/release.yml that invokes goreleaser on tag push, producing multi-arch binaries (linux / darwin / windows × amd64 / arm64) with sha256 checksums, publishing to GitHub Releases. Cut the first pre-GA tag (v0.1.0-rc1) and verify a6 update works against it end-to-end. Note: a7 is in the same gap; parallel follow-up at Wire .goreleaser.yml to a release workflow and cut the first tag a7#53.

6. CI matrix expansion (Expand CI matrix to APISIX 3.2/3.9/3.15 and add macOS #38). Add an APISIX version matrix to .github/workflows/e2e.yml (3.2 LTS, 3.9, 3.15). Add an OS matrix covering at least linux + macOS for unit and lint (windows is nice-to-have for the completion script path). Pin golangci-lint-action to an exact version rather than latest.

7. Coverage top-ups on named helper packages (Cover named helper packages: selector, tableprinter, root, configutil #39). Per Follow-up: a6 test / skills / docs review findings #14's 2026-04-28 boundary correction, future low-coverage work stays limited to self-contained unit tests on pure helpers, not mocked Admin-API command tests. Targets: pkg/selector, pkg/tableprinter, pkg/cmd/root, pkg/cmd/config/configutil. Also add invalid-parameter branch coverage for service + route + plugin-config combined scenarios (within the Admin-API boundary, not data-plane). No blanket coverage % target; each named package gets a per-package target set during the work.

8. Bug-class audit protocol (Adopt and document the bug-class audit protocol #40). Adopt a7's pattern: when a live-validation bug is found, identify the bug class and audit the rest of the codebase for the same shape. Document the protocol in AGENTS.md so it sticks.

9. CLI UX consistency sweep against live APISIX (CLI UX consistency sweep against live APISIX #41). Mirror a7 issues Land docs/ga-test-plan.md and achieve automated E2E parity with the manual pass #35, Eliminate silent test skips in test/e2e/ #36, Wire goreleaser, cut v0.1.0-rc1, and verify a6 update end-to-end #37, Validate every skill in skills/ end-to-end (no silent skips) #42, Define a6 GA scope and supported-version matrix #49 (scan every command for doc-vs-code flag mismatches, silently-dropped positional args, inconsistent --output defaults, and confusing --id semantics). Track findings as discrete sub-issues as they are discovered during the manual walkthrough.

10. Skills corpus validation (Validate every skill in skills/ end-to-end (no silent skips) #42). Every skill in skills/ must have a passing E2E test (no silent skips). Either fix the failing skills or remove them from the GA-supported set. Target: 40 / 40 green, or an explicit smaller "GA skills" subset documented in docs/ga-scope.md.

11. Reconcile pkg/httpmock doc wording (Reconcile pkg/httpmock doc wording in AGENTS.md #43). Update AGENTS.md line 57 to remove the "Legacy ... still under migration" label. httpmock is the standard unit-test pattern in both a6 and a7 (a7's AGENTS.md documents it as the canonical pattern). Optionally backport the RegisterResponder helper that a7 added if any a6 unit tests would benefit from request inspection.

12. debug logs abstraction (Abstract a6 debug logs from Docker-only deployment assumption #44). a6 debug logs currently assumes a Docker deployment and a discoverable container. Either abstract it for bare-metal / k8s / systemd installs or document the scope limit in docs/user-guide/debug.md and accept the constraint.

13. Docs hygiene and entry-point coverage (Docs hygiene: refresh roadmap, conditional-plugin notes, entry points #45). Fix the stale status table in docs/roadmap.md. Add docs for conditional plugins (skywalking et al). Add direct entry points in the user guide for context, config, update, version (per Follow-up: a6 test / skills / docs review findings #14 docs P2). Distinguish "verified in real env" vs. "conditional / skipped" in user-facing docs.

14. Governance and community files (Add governance files and enable branch protection on main #46). Add CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.md. Enable branch protection on main (require PR review, status checks).

15. Release notes and version-support statement (Draft GA release notes and version-support statement #47). Draft the GA release notes covering: supported APISIX versions, OS / arch matrix, the skills inventory that ships, known limitations (e.g. debug logs Docker-only if that's the resolution), and the unsupported-feature list if any are dropped during Define a6 GA scope and supported-version matrix #49.

16. Final GA readiness checklist verification (Final GA readiness checklist verification and release cut #48). Re-run the exit criteria below, confirm CI green on main, cut the GA release / tag.

Exit criteria

• GA scope and supported-version matrix documented (docs/ga-scope.md).
• All sub-issues above resolved or explicitly deferred with rationale.
• docs/ga-test-report.md Run 1 + Run 2 both green; report committed.
• 0 silently-skipped tests in test/e2e/ (or each documented + flag-gated).
• CI matrix: APISIX 3.2 / 3.9 / 3.15 all passing; lint pinned.
• Release workflow exists, has produced at least one signed multi-arch release, a6 update validated against it.
• Named helper packages (pkg/selector, pkg/tableprinter, pkg/cmd/root, pkg/cmd/config/configutil) at per-package coverage targets.
• Governance files in place; branch protection enabled on main.
• Release notes drafted and reviewed.

Related

• Parallel follow-up against a7 to wire its goreleaser config + cut its first tag: Wire .goreleaser.yml to a release workflow and cut the first tag a7#53.
• Pre-existing findings issue: Follow-up: a6 test / skills / docs review findings #14.