create a standard-document-template.md

hyperfleet/standards/standard-document-template.md

@@ -0,0 +1,287 @@
+# HyperFleet [Topic] Standard
+
+<!-- 
+  INSTRUCTIONS: Replace [Topic] with the specific topic name.
+  Examples: "Logging", "Error Model", "Health Endpoint", "Commit Message"
+
+  Delete this comment block and all other instruction comments before finalizing.
+-->
+
+This document defines the standard [describe what the standard covers] for all HyperFleet components (API, Sentinel, Adapters).
+
+---
+
+## Table of Contents
+
+<!-- 
+  INSTRUCTIONS: Include a Table of Contents for documents with 5+ sections.
+  Update section numbers and names to match your actual content.
+  For shorter documents, this section can be omitted.
+-->
+
+1. [Overview](#overview)
+2. [Section Name](#section-name)
+3. [Examples](#examples)
+4. [Action Items](#action-items)
+5. [References](#references)
+
+---
+
+## Overview
+
+### Goals
+
+<!-- 
+  INSTRUCTIONS: List 3-5 clear goals this standard achieves.
+  Use action-oriented language and focus on outcomes.
+-->
+
+- **Goal One**: Brief description of the first goal
+- **Goal Two**: Brief description of the second goal
+- **Goal Three**: Brief description of the third goal
+
+### Non-Goals
+
+<!-- 
+  INSTRUCTIONS: Explicitly state what this standard does NOT cover.
+  This helps prevent scope creep and sets clear boundaries.
+  Remove this section if not applicable.
+-->
+
+- What this standard intentionally does not address
+- Another out-of-scope item
+
+### Applicability
+
+<!-- 
+  INSTRUCTIONS: Define which components/repositories this standard applies to.
+  Remove this section if the standard applies to all HyperFleet components.
+-->
+
+This standard applies to:
+
+- All HyperFleet service repositories
+- All adapter repositories owned by hyperfleet team
+- Infrastructure and tooling repositories
+
+### Reference Implementation
+
+<!-- 
+  INSTRUCTIONS: If there is a shared library or reference implementation,
+  document it here with repository link and JIRA ticket.
+  Remove this section if not applicable.
+-->
+
+A shared Go library implementing this standard is available at:
+
+**Repository:** `github.com/openshift-hyperfleet/hyperfleet-[library-name]` *(planned - see [HYPERFLEET-XXX](https://issues.redhat.com/browse/HYPERFLEET-XXX))*
+
+---
+
+## Section Name
+
+<!-- 
+  INSTRUCTIONS: Add your main content sections here.
+  Use clear, descriptive headers that reflect the content.
+
+  Common patterns to follow:
+  - Use tables for structured information (fields, codes, mappings)
+  - Use code blocks with language tags for examples
+  - Use > **Note:** for important callouts
+  - Use **Rationale:** to explain design decisions
+-->
+
+### Subsection
+
+Description of this subsection's content.
+
+| Column 1 | Column 2 | Column 3 | Description |
+|----------|----------|----------|-------------|
+| Value 1  | Value 2  | Value 3  | What this row represents |
+| Value 4  | Value 5  | Value 6  | What this row represents |
+
+### Another Subsection
+
+<!-- 
+  INSTRUCTIONS: Use MUST, SHOULD, MAY consistently per RFC 2119:
+  - MUST: Absolute requirement
+  - SHOULD: Recommended but exceptions may exist
+  - MAY: Optional
+-->
+
+All components MUST implement the following:
+
+- Requirement one
+- Requirement two
+
+Components SHOULD also consider:
+
+- Recommendation one
+- Recommendation two
+
+> **Note:** Include important clarifications or edge cases that readers should be aware of.
+
+**Rationale:** Explain the reasoning behind design decisions when it helps readers understand why the standard exists.
+
+---
+
+## Configuration
+
+<!-- 
+  INSTRUCTIONS: If the standard involves configurable options,
+  document them in a table with flags, environment variables, and defaults.
+  Remove this section if not applicable.
+-->
+
+All components MUST support configuration via **command-line flags** and **environment variables**.
+
+| Option | Flag | Environment Variable | Default | Description |
+|--------|------|---------------------|---------|-------------|
+| Option Name | `--option-name` | `OPTION_NAME` | `default` | What this option controls |
+
+**Precedence** (highest to lowest): flags → environment variables → config file → defaults
+
+---
+
+## Component-Specific Guidelines
+
+<!-- 
+  INSTRUCTIONS: If different components have different requirements,
+  document them here. Remove this section if the standard applies
+  uniformly to all components.
+-->
+
+### API
+
+| Field | Description |
+|-------|-------------|
+| `field_name` | What this field represents |
+
+### Sentinel
+
+| Field | Description |
+|-------|-------------|
+| `field_name` | What this field represents |
+
+### Adapters
+
+| Field | Description |
+|-------|-------------|
+| `field_name` | What this field represents |
+
+---
+
+## Examples
+
+<!-- 
+  INSTRUCTIONS: Provide practical examples that demonstrate the standard.
+  Include both correct ("DO") and incorrect ("DON'T") examples where helpful.
+-->
+
+### Basic Example
+
+```text
+Example showing the basic format or usage
+```
+
+### Code Example
+
+```go
+// ✅ DO: Describe what makes this correct
+func correctExample() {
+    // Implementation following the standard
+}
+
+// ❌ DON'T: Describe what makes this incorrect
+func incorrectExample() {
+    // Implementation that violates the standard
+}
+```
+
+### Complete Example
+
+<!-- 
+  INSTRUCTIONS: Provide a comprehensive example that shows
+  all aspects of the standard working together.
+-->
+
+```json
+{
+  "field": "value",
+  "nested": {
+    "example": "data"
+  }
+}
+```
+
+---
+
+## Enforcement
+
+<!-- 
+  INSTRUCTIONS: Describe how this standard will be enforced.
+  Include both CI/automated enforcement and manual review expectations.
+  Remove this section if enforcement is not applicable.
+-->
+
+This standard will be enforced through:
+
+### CI Validation
+
+- **Tool Name**: Description of automated validation
+- See [HYPERFLEET-XXX](https://issues.redhat.com/browse/HYPERFLEET-XXX) for implementation status
+
+### Code Review
+
+- Reviewers should verify compliance during PR reviews
+- Non-compliant code should not be merged
+
+---
+
+## Action Items
+
+<!-- 
+  INSTRUCTIONS: List outstanding work and implementation items related to this standard.
+  Each item should have enough detail to be converted into a JIRA ticket.
+  Remove items as they are completed or converted to tickets.
+
+  Priority: High (blocking other work) | Medium (important) | Low (nice to have)
+  Size: S (< 1 day) | M (1-3 days) | L (3-5 days) | XL (needs breakdown)
+-->
+
+- **Action item name**
+  - Description: What needs to be done and why
+  - Acceptance Criteria: How to verify the work is complete
+  - Priority: High | Medium | Low
+  - Size: S | M | L | XL
+
+- **Another action item**
+  - Description: What needs to be done and why
+  - Acceptance Criteria: How to verify the work is complete
+  - Priority: High | Medium | Low
+  - Size: S | M | L | XL
+
+---
+
+## References
+
+### External Resources
+
+<!-- 
+  INSTRUCTIONS: Link to external specifications, RFCs, or documentation
+  that this standard is based on or related to.
+-->
+
+- [External Resource Name](https://example.com/resource)
+- [RFC XXXX - Description](https://www.rfc-editor.org/rfc/rfcXXXX.html)
+
+### Related HyperFleet Standards
+
+<!-- 
+  INSTRUCTIONS: Link to other HyperFleet standards that are related to this one.
+  Use relative paths for internal links.
+-->
+
+- [Logging Specification](./logging-specification.md)
+- [Error Model](./error-model.md)
+- [Health Endpoints](./health-endpoints.md)