Repository navigation
docs(contrib): contribution, development and AI agent structure (issue #16) - #106
senolcolak wants to merge 8 commits into
Conversation
First-ever intake templates for the tracker (issue #16): - bug.yml: structured bug form — service dropdown with ports, endpoint + method, microversion hints (Nova 2.1-2.90, Cinder 3.0-3.71), curl repro, and a REQUIRED expected-behavior field asking for the upstream docs.openstack.org/gophercloud citation (SPEC-000 compliance is priority zero, so the reference for 'correct' is always upstream). - feature.yml: problem statement, required upstream-parity target (including an explicit out for deliberately lightstack-specific proposals), proposed API surface, client-impact checkboxes (CLI, Terraform, Horizon, gophercloud — which drives contract-test prioritization). - config.yml: blank issues off; Discussions + private security advisory links, SBOM findings pointed at docs/security/SBOM_TRIAGE.md. - PULL_REQUEST_TEMPLATE.md: what/why with issue link, spec/ADR reference section, checklist (contract tests for API surface, make build, CHANGELOG [Unreleased], docs, per-commit Signed-off-by matching the actual 'SAP Sign-off Check' CI job, no secrets), testing-evidence block. Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
…op, review process The contributor definition issue #16 asks for (all facts verified against the repo): - Sign-off Requirement (DCO): the dco-check job ('SAP Sign-off Check') in ci.yml inspects EVERY commit in a PR for 'Signed-off-by: Name <name@sap.com>' and the aggregate CI Status job fails the PR without it. Documents git commit -s / --amend -s / rebase --signoff and links the DCO. This was previously enforced but documented nowhere — a first-time contributor's PR failed CI with no pointer to why. - Protected Branches: main, stable/**, releases/** — branch + PR only. - Review Process: the multi-round comprehensive review culture (severity- rated findings, dedicated fix commits, loop until clean, reports in docs/review/), with a real fix commit as the example. - Testing sections rewritten to the real loop: LIGHTSTACK_TEST_DB_URL (harness migrates, does not create the DB), contract-test workflow with the 5 known docker-exec environmental failures, chart-test, make lint. - Stale content fixed: Go 1.27.2 (go.mod), make migrate (not the nonexistent migrate-up), manual docker run postgres replaced by make db-up, dead docs/MVP_V1_COMPLETE.md reference dropped, shipped items (Floating IPs, L3 forwarding) pruned from Areas Needing Help, Placement item re-anchored, lowercase 'default' domain in the verify snippet corrected to 'Default' (Keystone resolves domain names case-sensitively). Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
AI-agent alignment, the other half of issue #16: CLAUDE.md referenced an 'Ultimate Project System' whose files do not exist in the repository — .beastmode/BEASTMODE.md (L0 autoload), .beastmode/context/{PHASE}.md, memory/constitution.md — so an agent following it literally hit dead paths. The rewrite keeps every piece of verified repo knowledge (architecture, config keys, tenancy caveats, conventions; the Nine Articles now stated inline) and drops the dead framing (slash-commands, swarm mode, persona). Stale facts corrected: seven listeners (Placement :8778), 70+ tables, pkg/hypervisor/ instead of the nonexistent xml_template.go, rate_limiting marked dead config. DB-backed test guidance now matches the actual harness (connects and migrates an existing scratch database; example points at lightstack_test, not the shared 'postgres' database). AGENTS.md (new, root): the tool-agnostic entry point — repo map, ground- truth commands, hard rules (DCO sign-off with sap.com address, protected branches, contract tests for API changes, tenant isolation security- critical per SPEC-022/023), working agreements (spec pattern, review-fix loops, changelog entries). Points to CLAUDE.md for Claude-specific depth and docs/CONTRIBUTING.md for the contribution process. Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
…template The Specifications side of issue #16's alignment chain. docs/specs/README.md was a stale March snapshot with every spec 'Draft'; it is now a live registry: one row per spec with an evidence-backed status (draft / accepted / implemented / superseded), commit and code-reference evidence, numbering rules (one number per spec, monotonic; the duplicate SPEC-025 dirs and the untracked 026 rename are documented as historical anomalies; next free number is 028), the lifecycle semantics, and a how-to-write-a- spec guide backed by docs/specs/_template/ — a skeleton mirroring the real pattern (spec.md with mandatory FR-NNN ids, plan.md, tasks.md in Tnnn test-first format, contracts/ with Given/When/Then tables that become the contract tests), modeled on 009-single-node-real-mode. Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
The Architectural-ADR side of the alignment chain. ADR-001 and ADR-002 existed by accident of history with no process defining when the form is required. ADR-000 sets the criteria — cross-cutting architectural decisions, hard-to-reverse choices, security/compliance posture changes, dependency changes — with ADR-001 (global DB pool to constructor injection) and ADR-002 (rate limiting architecture) as the worked examples, and clarifies that spec-local choices stay in the spec. The adr/README.md index gains the numbering convention (next free ADR-003), status values, and _TEMPLATE.md mirroring ADR-001's shape. Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
Closes the Specifications -> Contracts link issue #16 asks for and doubles as the gap list for issue #105 (testing). Built from test-source evidence (grep for SPEC-/FR-/US- citations in test/contract/), not assumption: inferred mappings are marked as such. Findings it surfaces: 20 of 97 contract test files cite a spec (Cinder 0/18, Glance 0/7 — the largest #105 back-fill clusters); 19 of 28 spec dirs have no pinning tests (expected for future services and non-API-observable infra specs, genuine gaps for the implemented SPEC-015/019/022 and the four unpinned contract areas of SPEC-024); the duplicate SPEC-025 dirs share FR numbering, so future citations should use the SPEC-025-followup form. Includes the maintenance commands to regenerate the counts. Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
Review SummaryThis PR went through the comprehensive review-fix loop before being opened. Round 1 — 6 findings (2 Medium, 4 Low), all fixed pre-push
Verdict: CLEANEvery commit hash, PR reference, CI job name, Makefile target, port, microversion, and version claim was verified against the tree by the reviewer; all YAML validated against the GitHub issue-forms schema; all relative links in the 15 new/changed files resolve. Verification
Merge notes
|
Review findings (comprehensive review of the open senolcolak PRs): - MEDIUM: CLAUDE.md gave Cinder an S3 backend and listed rbd,s3 as valid; only Glance supports S3 and rbd,s3 is rejected at startup. - MEDIUM: CLAUDE.md asserted '100% Terraform compatibility' and 'zero modifications', contradicted by the repo's own compatibility report and blueprint. Hedge to the validated topology and link the report. - MEDIUM: 'next free spec number is 028' collides with in-flight #107 and #108/#109. Freeze 028, name the claimants, and keep the later-merge renumber rule (no renumbering here). Flag #107's plan.md-only spec. - LOW: state Go 1.27.x and defer to go.mod, so #107's 1.27.3 bump does not instantly stale the floor. - LOW: registry PR citations #515-#549 are cloud-storage PRs, not this repo's; prefix them. SPEC-019 cites commit 0a4dde0. - LOW: AGENTS.md pointed the DB tests at the shared postgres database; standardize on lightstack_test. Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
Shared CI unblocker for the open PRs (independent of this PR's content): - govulncheck now reports GO-2026-6809 in crypto/x509 (reachable through the HTTP server), fixed in Go 1.27.3. Main pins 1.27.2 everywhere, so every PR's Runtime Vulnerabilities and SBOM job fails. Pin 1.27.3 in go.mod, tools/go.mod, CI workflows, the builder image, the test container and the single-node deploy script (version + sha256). - The unpinned Helm install now pulls Helm 4, whose 'helm plugin install' rejects the helm-unittest source without --verify=false, failing the Helm Charts job with 'plugin source does not support verification'. Install Helm 3.22.1 and helm-unittest 1.2.1 in an isolated plugin dir, matching PR #107, so the gate is version-stable. Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
Comprehensive review — findings fixedRe-reviewed against Found 10 (6 Medium, 4 Low) — mechanical/pre-merge items fixed in
Left as coordination notes (not defects to fix here): #107's spec dir is plan.md-only and needs spec.md/tasks.md or a documented plan-first carve-out; #103's guard will require CONTRIBUTING's contract-test startup to use CI unblocker included ( CI: 10/10 green. |
Closes #16
What & why
Implements issue #16 — proper Contribution, Development and AI Agent structure — across its three named deliverables (contributor definition, issue/bug/feature templates, Specifications → Contracts → ADRs alignment) plus the AI-agent alignment from the title.
1. Intake templates (first ever in this repo)
.github/ISSUE_TEMPLATE/{bug,feature,config}.yml+.github/PULL_REQUEST_TEMPLATE.md— bug reports require the upstream OpenStack reference for expected behavior (SPEC-000 compliance is priority zero); feature requests require the upstream-parity target and client-impact checkboxes; the PR checklist carries the DCO sign-off item matching the actualSAP Sign-off CheckCI job.2. Contributor definition
docs/CONTRIBUTING.md— the previously invisible hard rules: every commit needsSigned-off-by: Name <name@sap.com>(the dco-check CI job rejects PRs without it — this was enforced but documented nowhere), protected branches (main,stable/**,releases/**), the real dev loop (LIGHTSTACK_TEST_DB_URL, contract-test workflow with the 5 known docker-exec failures,make chart-test,make lint), and the review-fix-loop culture. Stale content fixed (Go 1.27.2,make migratenotmigrate-up, shipped items pruned from Areas Needing Help).3. AI agent alignment
CLAUDE.mdreferenced an "Ultimate Project System" whose files do not exist in the repository (.beastmode/BEASTMODE.md,memory/constitution.md, phase contexts) — agents following it hit dead paths. Rewritten with zero dead references, all verified knowledge preserved, stale facts corrected (seven listeners, 70+ tables). New rootAGENTS.mdas the tool-agnostic entry point (repo map, ground-truth commands, hard rules, working agreements).4. Specifications → Contracts → ADRs
docs/specs/README.md— live registry with evidence-backed statuses (was: everything "Draft", March snapshot), numbering rules (duplicate SPEC-025s documented, next free 028), lifecycle, spec-writing guidedocs/specs/_template/— spec skeleton mirroring the real pattern (FR-NNN ids, test-first tasks, Given/When/Then contracts)docs/specs/CONTRACT-INDEX.md— the SPEC ↔ contract-test cross-index, mined from test sources: 20/97 test files cite a spec (Cinder 0/18, Glance 0/7); genuine gaps: implemented-but-unpinned SPEC-015/019/022 and SPEC-024's four unpinned contract areas — doubles as the gap list for issue [Enhancement] Testing #105docs/adr/— ADR-000 (when an ADR is required), index with numbering convention, templateReview
Went through the comprehensive review loop: round 1 found 6 findings (2 Medium: an example commit cited as merged that is from an open PR; DB-test guidance claiming the harness creates databases when it only connects+migrates — contradicting CONTRIBUTING; 4 Low: nonexistent
lightstack --versionflag in the bug form, wrong upstream microversion/field names in template placeholders, a doc link that never mentions Placement, lowercase domain in a snippet) — all fixed. Every commit hash, PR reference, code-reference count, CI job name, Makefile target, port, and version claim in the change was verified against the tree by the reviewer.Testing evidence
Note: describes
main's behavior (no secret-guard/LIGHTSTACK_ADMIN_PASSWORD content — that arrives via #103 and gets documented there).Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>(DCO — SAP Sign-off Check)