feat: Add guild charters and task boards for various components
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled

- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform.
- Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds.
- Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies.
- Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
This commit is contained in:
2025-11-01 02:21:46 +02:00
parent e5629454cf
commit 66cb6c4b8a
227 changed files with 9913 additions and 6210 deletions

View File

@@ -0,0 +1,37 @@
# API Contract Contribution Guide
This guide explains how to propose, review, and publish API contract changes across StellaOps services. Follow these steps whenever you modify an OpenAPI specification or an externally supported endpoint.
## 1. Background
- Public APIs are defined in `src/Api/StellaOps.Api.OpenApi` (aggregate spec) and per-service OpenAPI documents.
- Compatibility checks run in CI via the API Governance tooling (`StellaOps.Api.Governance`).
- Docs & SDK guilds consume the generated specs to publish references and SDK packages.
## 2. Workflow
1. **Design review** capture the proposed endpoint or schema change in the relevant modules `TASKS.md` and link to any ADR or design doc.
2. **Spec update** modify the service-specific OpenAPI file under `src/Api/StellaOps.Api.OpenApi/<service>/`.
3. **Run governance checks** execute `dotnet test src/Api/StellaOps.Api.Governance.Tests` to validate lint rules, backwards compatibility, and examples.
4. **Regenerate aggregate spec** run `dotnet run --project src/Api/StellaOps.Api.OpenApi` to update `stella.yaml`.
5. **Update docs** adjust the corresponding module dossier (`docs/modules/<component>/architecture.md` or guides) to reflect new/changed endpoints.
6. **Notify SDK/Docs guilds** coordinate SDK regeneration (`src/Sdk/StellaOps.Sdk.Generator`) and release notes.
## 3. Backwards Compatibility Rules
- Avoid breaking changes (removing endpoints/fields, altering semantics). If unavoidable, document deprecation timelines and fallback behaviour.
- Additive changes (new optional fields, new endpoints) require version bump and changelog entry.
- Error responses must remain structured; return `application/problem+json` payloads with stable error codes.
## 4. Tooling
- `dotnet tool run stellaops-api-lint` local lint.
- `dotnet run --project src/Api/StellaOps.Api.OpenApi -- --validate` schema validation.
- `docs/09_API_CLI_REFERENCE.md` update CLI reference when command behaviour shifts.
## 5. References
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/cli/architecture.md`
- `src/Api/StellaOps.Api.Governance`
- `src/Api/StellaOps.Api.OpenApi`