Skip to content

Naming and path conventions

Purpose: Define stable naming and path conventions used across the documentation portal and HybridOps runtime.

This standard applies to all governed document families (ADRs, contracts, standards, runbooks, HOWTOs, CI guides) and to runtime artefact paths produced by hyops.

1. Naming conventions

  • File and directory names use lowercase kebab-case unless a governed identifier requires an uppercase prefix.
  • Governed identifiers use fixed prefixes and category-based numeric blocks:
  • ADR-CCNN
  • RB-CCNN
  • HOWTO-CCNN
  • CI-CCNN
  • Identifiers referenced by automation and tooling MUST remain stable once published.

1.1 Runtime resource naming (HyOps operators)

To support multi-environment operations on shared infrastructure (for example a single Proxmox cluster hosting shared, dev, staging, and prod), HybridOps distinguishes between:

  • Logical identifiers (stable automation keys used in module inputs, state, and inventory contracts)
  • Physical/display names (provider-visible names such as Proxmox VM names and NetBox VM names)

Norms:

  • Logical identifiers MUST remain stable within a module/blueprint contract and SHOULD be service-oriented.
  • Examples:
    • rke2-cp-01, rke2-wkr-01
    • pgha-01, pgha-02, pgha-03
    • pgcore-01
  • Physical/display names SHOULD be environment-scoped by default to avoid collisions on shared metal.
  • Recommended pattern: <env>-<service>-<ordinal>
  • Examples:
    • shared-pgcore-01
    • shared-netbox-01
    • dev-pgha-01
    • prod-rke2-cp-01
  • HyOps blueprints/modules SHOULD remain generic and MUST NOT hardcode environment names (for example dev, prod) into logic unless explicitly modelling a controlled cross-environment dependency.
  • The execution namespace is provided at runtime via --env <name>.
  • When a specific cluster/service needs clearer operator-facing names, use explicit physical-name overrides (for example vm_name or name_prefix) while preserving logical identifiers for contracts/state.

1.2 Network alias naming (HyOps bridge abstractions)

HyOps may expose stable bridge aliases to blueprints (for example vnetenv, vnetenvdata) while resolving them to provider-constrained names internally.

Norms:

  • Blueprint/operator-facing aliases SHOULD remain semantic and environment-aware.
  • Provider-specific internal keys MAY be shortened to satisfy provider constraints (for example length limits), but this translation MUST be deterministic and documented in module/runbook documentation.
  • Documentation and runbooks SHOULD describe the operator-facing alias first; internal provider key names are implementation details unless troubleshooting requires them.

Where:

  • CC is the category code (00–09).
  • NN is the sequence within the category (01–99).

2. Documentation repository structure

Paths are expressed relative to the documentation repository root (docs/).

  • ADRs: docs/adr/
  • Contracts: docs/architecture/contracts/
  • Standards: docs/architecture/standards/
  • Diagrams: docs/architecture/diagrams/
  • Runbooks: docs/ops/runbooks/
  • CI guides: docs/ops/ci/
  • Guides: docs/guides/
  • HOWTOs: docs/howto/
  • Platform catalogs: docs/platform/
  • Briefings: docs/briefings/

Norms:

  • Contracts and standards define normative behaviour and conventions.
  • Runbooks and HOWTOs define procedures.
  • Platform catalog pages provide navigation and inventory and MUST NOT duplicate normative content.

3. Runtime root paths

Default runtime root is ~/.hybridops unless overridden by:

  • --root <dir> or $HYOPS_RUNTIME_ROOT
  • --env <name> or $HYOPS_ENV (namespaced runtime under ~/.hybridops/envs/<name>/)

--root and --env are mutually exclusive.

Reserved directories under <root>:

  • config/ — non-secret configuration
  • credentials/ — sensitive credential files (mode 0600 where supported)
  • vault/ — encrypted env bundles
  • meta/ — readiness markers and runtime stamps
  • logs/ — evidence and redacted logs
  • state/ — module state snapshots and driver-managed state
  • work/ — execution scratch

Targets, drivers, and modules MUST NOT write outside <root> unless explicitly documented and approved by an ADR.

4. Evidence paths

Evidence paths are stable in structure and vary only by target/module/driver identifiers and run_id:

  • Init: <root>/logs/init/<target>/<run_id>/
  • Module: <root>/logs/module/<module_id>/<run_id>/
  • Driver: <root>/logs/driver/<driver_id>/<run_id>/

Evidence artefacts MUST be redacted and MUST NOT contain secrets.

5. Header conventions

This standard defines a minimal, enforceable header policy for maintainability without over-governance.

5.1 Scope

  • Boundary files (public entrypoints, registries, routers, contracts, standards, and any file that defines a stable interface) MUST include the full header.
  • Leaf files (simple implementations, small helpers, or internal-only modules) MAY use a minimal header or omit the header if the intent is obvious from file name and location.

5.2 Full header

The full header MUST include:

  • purpose: one sentence describing what the file does.
  • Architecture Decision: ADR reference or ADR-N/A where applicable.
  • maintainer: HybridOps.Studio.

Example:

"""
purpose: <one sentence>
Architecture Decision: ADR-XXXX (<short name>) | ADR-N/A (<reason>)
maintainer: HybridOps.Studio
"""

5.3 Minimal header

For leaf files, the minimal header (when used) SHOULD include:

  • purpose: only.

Example:

"""purpose: <one sentence>"""

5.4 Non-goals

  • This standard does not require a uniform header on every file.
  • This standard does not require names or dates in code headers.

6. Cross-linking rules

  • Contracts MAY link to annexes and related contracts/standards.
  • Runbooks and HOWTOs SHOULD link to relevant contracts/standards for normative rules.
  • Catalog pages SHOULD link to contracts/runbooks/HOWTOs and MUST NOT copy their content.