Skip to content

docs(contrib): contribution, development and AI agent structure (issue #16) - #106

Open
senolcolak wants to merge 8 commits into
mainfrom
feature/contribution-and-agent-structure
Open

senolcolak wants to merge 8 commits into
mainfrom
feature/contribution-and-agent-structure

Conversation

@senolcolak

Copy link
Copy Markdown
Collaborator

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 actual SAP Sign-off Check CI job.

2. Contributor definition

docs/CONTRIBUTING.md — the previously invisible hard rules: every commit needs Signed-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 migrate not migrate-up, shipped items pruned from Areas Needing Help).

3. AI agent alignment

CLAUDE.md referenced 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 root AGENTS.md as 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 guide
  • docs/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 #105
  • docs/adr/ — ADR-000 (when an ADR is required), index with numbering convention, template

Review

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 --version flag 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

YAML: all 3 issue forms parse with correct issue-forms schema
Links: all relative links in 15 new/changed files resolve in the tree
No Go code touched — build unaffected

Note: describes main's behavior (no secret-guard/LIGHTSTACK_ADMIN_PASSWORD content — that arrives via #103 and gets documented there).

  • Every commit carries Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com> (DCO — SAP Sign-off Check)
  • No secrets, tokens, or credentials in the diff
  • Docs updated (this PR is docs)

Uwe Schwaeke added 6 commits October 14, 2026 19:27
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>
@senolcolak

Copy link
Copy Markdown
Collaborator Author

Review Summary

This PR went through the comprehensive review-fix loop before being opened.

Round 1 — 6 findings (2 Medium, 4 Low), all fixed pre-push

Severity Finding Fix
Medium CONTRIBUTING cited fix-commit 0e14680 as coming from a merged PR — it's from an open PR Reworded to name the open PR honestly
Medium CLAUDE.md/AGENTS.md claimed the DB-test harness "creates scratch databases" — it only connects + migrates (contradicted CONTRIBUTING) Both corrected; example URL now points at lightstack_test, not the shared postgres DB
Low bug.yml asked for lightstack --version (flag doesn't exist on main; arrives in #103) Now references CHANGELOG.md
Low feature.yml placeholder said "since microversion 2.21" (it's 2.1); bug.yml said task_vm_state (real field is OS-EXT-STS:task_state) Corrected to upstream facts
Low CONTRIBUTING Placement item linked STUB_PLACEHOLDERS.md which never mentions Placement Re-anchored to STATUS.md + internal/placement/placement.go
Low Verify snippet used lowercase default domain Default (Keystone resolves domain names case-sensitively)

Verdict: CLEAN

Every 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

  • ✅ CI 10/10 green (Build & Lint, Unit, Contract, Integration, Ceph RGW, Helm, SBOM, CI Status)
  • ✅ DCO / SAP Sign-off Check: all 6 commits carry Signed-off-by: Uwe Schwaeke <uwe.schwaeke@sap.com>
  • ✅ Docs/templates only — no Go code touched

Merge notes

Uwe Schwaeke added 2 commits November 2, 2026 10:26
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>
@senolcolak

Copy link
Copy Markdown
Collaborator Author

Comprehensive review — findings fixed

Re-reviewed against origin/main @ e909227; re-derived the CONTRACT-INDEX counts (20/97 files cite a spec; table is byte-exact against 97 test files), verified every cited commit hash, and re-checked all facts against the tree.

Found 10 (6 Medium, 4 Low) — mechanical/pre-merge items fixed in b38fc63.

Severity Finding Fix
Med CLAUDE.md gave Cinder an S3 backend and listed rbd,s3 as valid Cinder is stub/local/rbd/local,rbd; S3 is Glance-only; rbd,s3 marked rejected (matches STORAGE_MODES.md and AGENTS.md)
Med "100% Terraform compatibility" / "zero modifications", contradicted by the repo's own compatibility report Hedged to the validated topology, port-id workaround, object-storage exclusion; links the report and blueprint §6
Med "next free spec number is 028" collides with in-flight #107 and #108/#109 028 frozen with the claimants named and the later-merge renumber rule; no renumbering performed
Low Go 1.27.2 floor drifts when #107 lands "Go 1.27.x — use the exact version pinned in go.mod"
Low Registry #515–#549 are cloud-storage PRs, auto-linking to unrelated lightstack PRs; SPEC-019's #532 unverifiable Prefixed cloud-storage#NNN; SPEC-019 cites commit 0a4dde0
Low AGENTS.md pointed DB tests at the shared postgres database Standardized on lightstack_test with the one-time CREATE

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 make run/env vars; #101 conflicts in CLAUDE.md/CONTRIBUTING.md and its Terraform hedges must win on resolution.

CI unblocker included (3d76b0e): Go 1.27.3 for GO-2026-6809 + pinned Helm (was failing every PR's SBOM/Helm jobs).

CI: 10/10 green.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

proper Contribution, Development and AI Agent structure

1 participant