diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..f420d71 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,159 @@ +name: Bug report +description: Report a defect or regression in an existing spod capability. +title: "[bug] " +body: + - type: markdown + attributes: + value: | + Use this form for behavior that is incorrect relative to an existing capability or documented contract. + + Please avoid reporting missing/new capabilities as bugs; use the feature or use-case template instead. + + - type: textarea + id: summary + attributes: + label: Summary + description: What is broken? Describe the defect in one or two clear paragraphs. + placeholder: The service accepts ... but then ... + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Area + description: Which part of spod is primarily affected? + options: + - Service orchestration + - CLI + - REST API + - Configuration / mission profiles + - Input resolution / ingestion + - POD workflow + - Products / artifacts + - QC / validation / reporting + - Provenance / manifests + - Deployment / Docker + - Observability + - Build / CI / tooling + - Documentation + - Other + validations: + required: true + + - type: dropdown + id: severity + attributes: + label: Severity + description: What is the practical impact? + options: + - Critical — corrupt/invalid scientific or operational result without an explicit failure + - High — supported workflow is unusable or materially wrong + - Medium — degraded behavior with a workaround + - Low — minor defect or polish issue + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should happen according to the supported product behavior or documentation? + placeholder: | + Given ... + When ... + Then ... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happens instead? + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction steps + description: Provide the smallest reliable sequence that reproduces the issue. + placeholder: | + 1. Use config ... + 2. Run ... + 3. Inspect ... + 4. Observe ... + validations: + required: true + + - type: textarea + id: config + attributes: + label: Relevant configuration or input contract + description: Include the minimal relevant configuration. Remove secrets, credentials, and private data. + render: yaml + + - type: textarea + id: evidence + attributes: + label: Evidence + description: Add logs, error output, artifact paths, numerical differences, screenshots, or hashes that demonstrate the issue. + placeholder: Paste concise evidence here. + + - type: textarea + id: environment + attributes: + label: Environment + description: Include spod version/commit, Siderust version, Rust version, OS, container image, and deployment mode when relevant. + placeholder: | + spod: + Siderust: + Rust: + OS: + Deployment: + validations: + required: true + + - type: dropdown + id: regression + attributes: + label: Regression? + description: Did this capability work previously? + options: + - "Yes" + - "No" + - Unknown + validations: + required: true + + - type: textarea + id: capability_impact + attributes: + label: Product capability impact + description: Which documented workflow, use case, artifact, API contract, or product capability is affected? + placeholder: This breaks / degrades ... + validations: + required: true + + - type: textarea + id: done + attributes: + label: Definition of fixed + description: State what must be true to close the bug, including the regression test or verification evidence. + placeholder: | + - [ ] Reproduction fails before the fix and passes after it. + - [ ] Existing product-level behavior remains unchanged. + - [ ] Relevant integration/E2E coverage is added. + validations: + required: true + + - type: checkboxes + id: hygiene + attributes: + label: Checklist + options: + - label: I searched existing issues and did not find an equivalent report. + required: true + - label: I removed secrets, credentials, and private mission data from the report. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 0000000..a32ecf3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,100 @@ +name: Documentation +description: Create, correct, or improve product, architecture, operational, or developer documentation. +title: "[docs] " +body: + - type: markdown + attributes: + value: | + Documentation is part of the product contract. Use this template when documentation is missing, stale, misleading, or insufficient to verify supported behavior. + + - type: dropdown + id: kind + attributes: + label: Documentation type + options: + - Product / positioning + - Use case / workflow + - User guide / operations + - CLI / REST API + - Configuration / schema + - Architecture / ownership boundary + - Scientific assumptions / validation + - Deployment / observability + - Developer / contributing + - Examples + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Documentation problem + description: What is missing, wrong, stale, ambiguous, or difficult to verify? + validations: + required: true + + - type: textarea + id: audience + attributes: + label: Audience + description: Who should be able to use this documentation? + placeholder: Operator, integrator, contributor, flight-dynamics engineer, reviewer, ... + validations: + required: true + + - type: textarea + id: source_of_truth + attributes: + label: Source of truth + description: Which code, issue, schema, use case, standard, or external specification should the documentation agree with? + placeholder: | + - ... + - ... + validations: + required: true + + - type: textarea + id: scope + attributes: + label: Required content + description: List the concepts, workflows, examples, limitations, or decisions the documentation must cover. + placeholder: | + - ... + - ... + validations: + required: true + + - type: textarea + id: examples + attributes: + label: Examples / evidence + description: Include concrete commands, configs, API exchanges, artifacts, or diagrams that should be documented. + + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: Define how reviewers can verify the documentation is complete and accurate. + placeholder: | + - [ ] ... + - [ ] No stale ownership/API claims remain. + - [ ] Commands/examples are executable or covered by tests where practical. + validations: + required: true + + - type: textarea + id: related + attributes: + label: Related issues / use cases + description: Link the product capability or use case this documentation explains. + + - type: checkboxes + id: hygiene + attributes: + label: Checklist + options: + - label: I checked current documentation for an existing canonical page before proposing a duplicate. + required: true + - label: This request identifies a source of truth rather than relying on undocumented assumptions. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..866489f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,159 @@ +name: Feature request +description: Propose a new or expanded spod product capability. +title: "[feature] " +body: + - type: markdown + attributes: + value: | + Use this form for a capability that should become part of the spod product. + + Reusable scientific algorithms, parsers, and numerical primitives normally belong in Siderust. spod should own operational workflows, policy, orchestration, artifacts, interfaces, and product behavior. + + - type: textarea + id: problem + attributes: + label: Problem / opportunity + description: Describe the user or operational problem before proposing implementation details. + placeholder: Operators currently have to ... + validations: + required: true + + - type: textarea + id: user + attributes: + label: Target user / persona + description: Who needs this and in what context? + placeholder: LEO operator, flight-dynamics engineer, ground-segment integrator, SRE, ... + validations: + required: true + + - type: textarea + id: capability + attributes: + label: Proposed capability + description: What should spod be able to do when this is complete? + placeholder: spod should ... + validations: + required: true + + - type: dropdown + id: ownership + attributes: + label: Intended ownership + description: Where should the implementation primarily live? + options: + - spod — workflow / orchestration / product behavior + - spod — interface / artifact / operational policy + - Siderust — reusable scientific or format capability + - Upstream gap first — spod needs it but canonical science is missing + - Reference example / mission-specific extension + - Unsure — requires architecture review + validations: + required: true + + - type: textarea + id: workflow + attributes: + label: User workflow + description: Describe the expected interaction from input/request to result. + placeholder: | + 1. User provides ... + 2. spod resolves ... + 3. Siderust computes ... + 4. spod publishes ... + validations: + required: true + + - type: textarea + id: inputs + attributes: + label: Inputs / preconditions + description: List required datasets, configuration, state, permissions, or preconditions. + placeholder: | + - ... + - ... + validations: + required: true + + - type: textarea + id: outputs + attributes: + label: Outputs / observable behavior + description: What artifacts, API responses, status, reports, or side effects must be produced? + placeholder: | + - ... + - ... + validations: + required: true + + - type: textarea + id: requirements + attributes: + label: Functional and operational requirements + description: Include important semantics, failure behavior, reproducibility, provenance, latency, or quality requirements. + placeholder: | + - Must ... + - Must not silently ... + - Unsupported combinations must ... + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: Write externally verifiable criteria. Prefer checkboxes and observable outcomes over implementation details. + placeholder: | + - [ ] ... + - [ ] ... + - [ ] ... + validations: + required: true + + - type: textarea + id: verification + attributes: + label: Verification strategy + description: How will we prove the capability works and remains working? + placeholder: | + - Unit/integration/E2E coverage: + - Reference dataset: + - CLI/REST verification: + - Numerical/QC tolerances: + validations: + required: true + + - type: textarea + id: dependencies + attributes: + label: Dependencies / upstream gaps + description: Link related spod or Siderust issues and identify blockers. + + - type: textarea + id: non_goals + attributes: + label: Non-goals + description: Explicitly state what this feature should not expand into. + placeholder: | + - ... + - ... + + - type: textarea + id: value + attributes: + label: Product value + description: Why is this worth building? Describe operational, commercial, reliability, or user value. + validations: + required: true + + - type: checkboxes + id: hygiene + attributes: + label: Checklist + options: + - label: I checked that this is not already covered by an existing issue/use case. + required: true + - label: I considered whether reusable science belongs upstream in Siderust instead of spod. + required: true + - label: The acceptance criteria describe observable product behavior. + required: true diff --git a/.github/ISSUE_TEMPLATE/use-case.yml b/.github/ISSUE_TEMPLATE/use-case.yml new file mode 100644 index 0000000..c4dfd2b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/use-case.yml @@ -0,0 +1,224 @@ +name: Product use case +description: Specify an end-to-end user outcome that doubles as product documentation and a verification contract. +title: "[use case] " +body: + - type: markdown + attributes: + value: | + A use case is a **living product specification**. + + It should explain why the capability exists, how a user experiences it, what goes in and out, which layer owns each responsibility, and how we can prove the workflow works. + + A use case is not complete when code merely exists. It is complete when the documented outcome is reproducible and verified. + + - type: textarea + id: outcome + attributes: + label: Desired outcome + description: State the end-to-end result in one sentence from the user's perspective. + placeholder: As a ..., I want ..., so that ... + validations: + required: true + + - type: textarea + id: customer + attributes: + label: User / customer / actor + description: Who performs or benefits from this workflow, and in what operational context? + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem being solved + description: What currently costs time, expertise, reliability, or operational risk? + validations: + required: true + + - type: dropdown + id: status + attributes: + label: Product status + description: How should this use case be treated? + options: + - Core product use case + - Product extension + - Reference / example use case + - Experimental / discovery + validations: + required: true + + - type: textarea + id: trigger + attributes: + label: Trigger / entry condition + description: What causes the workflow to start, and what must already be true? + placeholder: A new observation arc becomes available ... + validations: + required: true + + - type: textarea + id: inputs + attributes: + label: Inputs + description: List datasets, configuration, mission metadata, state, credentials, or other required inputs. + placeholder: | + - Input: + - source: + - required fields/coverage: + - ... + validations: + required: true + + - type: textarea + id: workflow + attributes: + label: End-to-end workflow + description: Document the user-visible sequence, including important branches and failure behavior. + placeholder: | + 1. ... + 2. ... + 3. ... + validations: + required: true + + - type: textarea + id: spod_responsibilities + attributes: + label: spod responsibilities + description: What must the product own in this use case? Focus on orchestration, policy, interfaces, artifacts, and operational behavior. + placeholder: | + - validate ... + - resolve ... + - orchestrate ... + - publish ... + validations: + required: true + + - type: textarea + id: siderust_responsibilities + attributes: + label: Siderust / upstream responsibilities + description: Which reusable scientific, numerical, format, or standards functionality must remain canonical upstream? + placeholder: | + - format parsing ... + - observation model ... + - propagation ... + validations: + required: true + + - type: textarea + id: outputs + attributes: + label: Outputs / artifacts / API results + description: List every externally relevant result a successful workflow produces. + placeholder: | + - orbit product: + - QC report: + - manifest: + - API result: + validations: + required: true + + - type: textarea + id: quality + attributes: + label: Quality, correctness, and operational gates + description: Define what distinguishes a merely completed run from an acceptable result. + placeholder: | + - convergence: + - coverage: + - residual/QC thresholds: + - latency: + - provenance: + validations: + required: true + + - type: textarea + id: failure_modes + attributes: + label: Expected failure modes + description: Define important unsupported, invalid, degraded, or unavailable-data cases and how they should surface. + placeholder: | + - Missing ... + - Unsupported ... + - Quality gate ... + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: These are the functional contract for implementation and review. + placeholder: | + - [ ] ... + - [ ] ... + - [ ] ... + validations: + required: true + + - type: textarea + id: verification + attributes: + label: Verification evidence + description: Define the datasets, tests, commands, API calls, artifacts, metrics, or tolerances that prove the use case. + placeholder: | + Reference data: + Commands/API: + Expected artifacts: + Numerical/QC tolerances: + CI/E2E coverage: + validations: + required: true + + - type: textarea + id: observability + attributes: + label: Observability / supportability + description: What should an operator be able to inspect when this use case runs? + placeholder: Status, logs, metrics, warnings, artifact metadata, provenance, ... + + - type: textarea + id: dependencies + attributes: + label: Dependencies / related capabilities + description: Link prerequisite features, upstream gaps, standards, and related use cases. + + - type: textarea + id: non_goals + attributes: + label: Non-goals + description: Define boundaries so the use case does not accidentally expand the product surface. + placeholder: | + - ... + - ... + + - type: textarea + id: docs + attributes: + label: Documentation deliverables + description: What user-facing documentation must exist when this use case is implemented? + placeholder: | + - product/use-case page + - runnable example/config + - API/CLI documentation + - limitations + validations: + required: true + + - type: checkboxes + id: completion + attributes: + label: Product verification contract + description: These conditions should remain true when the issue is closed. + options: + - label: The implemented workflow matches the documented inputs, outputs, and failure behavior. + required: true + - label: Reusable science is consumed from Siderust or an explicit upstream-gap issue exists. + required: true + - label: Product-level integration/E2E verification is defined. + required: true + - label: The use case can remain as living documentation after implementation. + required: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 330869c..bd3db5a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,14 @@ The main foundational dependencies are released versions of `siderust`, `princip If a change requires unreleased functionality from one of those projects, do not add a local path or git dependency as a permanent workaround. Prefer opening or referencing the corresponding upstream change and keep this repository on released dependencies. +## Opening issues + +Use the structured GitHub issue forms for bugs, features, documentation work, and product use cases. + +Product use cases are treated as living specifications: they document the user outcome, product/upstream ownership boundary, inputs, outputs, quality gates, acceptance criteria, and the evidence required to verify the workflow. + +See [docs/contributing/issues.md](docs/contributing/issues.md) for the issue lifecycle and verification guidelines. + ## Before opening a pull request Run the same checks expected by CI: diff --git a/docs/contributing/issues.md b/docs/contributing/issues.md new file mode 100644 index 0000000..9496e6f --- /dev/null +++ b/docs/contributing/issues.md @@ -0,0 +1,115 @@ +# Issue and use-case guidelines + +GitHub issues in `spod` are part of the product-development system, not only a task queue. + +The repository provides four issue forms: + +| Template | Use it for | +|---|---| +| Bug | Incorrect behavior or regression in an existing supported capability | +| Feature | A new or expanded product capability | +| Documentation | Missing, stale, misleading, or unverifiable documentation | +| Product use case | An end-to-end user outcome that acts as product documentation and a verification contract | + +## Product boundary + +When opening or refining an issue, preserve the architectural distinction: + +### Siderust + +Owns reusable scientific and numerical functionality, including standard-format parsing, astrodynamics, observation models, estimation primitives, and reusable scientific QC. + +### spod + +Owns product workflows, orchestration, mission configuration, operational policy, artifacts, provenance, CLI/REST interfaces, deployment, observability, and product-level verification. + +A feature request should not introduce a second implementation in `spod` when canonical reusable science belongs in Siderust. + +If `spod` requires a capability that Siderust does not yet provide with the required semantics, classify it as an **upstream gap** and preserve the product requirement explicitly. + +## Use cases as living specifications + +A product use case should survive implementation. + +The issue describes: + +```text +user/problem + | + v +inputs + trigger + | + v +documented workflow + | + +---- Siderust scientific responsibilities + | + +---- spod product responsibilities + | + v +outputs + artifacts + | + v +quality gates + | + v +verification evidence +``` + +This makes the issue useful in three phases: + +1. **Discovery/documentation** — explains why the capability exists and its boundaries. +2. **Implementation** — provides the functional contract and acceptance criteria. +3. **Verification/maintenance** — records how the behavior is proven and what future changes must preserve. + +## Acceptance criteria + +Good acceptance criteria describe externally observable outcomes. + +Prefer: + +```text +- [ ] Every consumed input is represented in run provenance. +- [ ] An unsupported force model returns an explicit configuration error. +- [ ] CLI and REST execute the same service workflow. +``` + +Avoid criteria that only prescribe internal implementation: + +```text +- [ ] Create struct Foo. +- [ ] Add function bar(). +``` + +Internal design may change while the product contract remains stable. + +## Verification evidence + +Issues should identify how the behavior will be proven. Depending on the capability, that may include: + +- unit tests; +- integration tests; +- end-to-end workflows; +- reference datasets; +- numerical tolerances; +- generated artifacts and hashes; +- CLI commands; +- REST exchanges; +- QC thresholds; +- Docker/service smoke tests; +- documentation examples exercised by CI. + +For scientific workflows, a green process exit is not sufficient evidence of product correctness. + +## Closing an issue + +Before closing a feature or use case, reviewers should be able to answer: + +- Does the implementation satisfy the documented user outcome? +- Are inputs, outputs, failure modes, and quality gates represented correctly? +- Is reusable scientific functionality in the correct upstream layer? +- Is product-level verification present? +- Does current user-facing documentation match the implemented behavior? +- Would a future contributor understand what must not regress? + +A closed use-case issue should therefore remain useful as historical and functional product documentation.