# Understanding the File Header Convention in ODS Installer Modules

> Learn the ODS installer module file header convention. Discover the three-section format Purpose, Expects, and Provides for clear script intent, environment variables, and exported outputs.

- Repository: [Osmantic/ODS](https://github.com/Osmantic/ODS)
- Tags: how-to-guide
- Published: 2026-09-02

---

**All installer modules in the Osmantic/ODS repository follow a strict three-section header format consisting of Purpose, Expects, and Provides comments that declare the script's intent, required environment variables, and exported outputs.**

The Osmantic/ODS (Open Dependability Stack) project maintains rigorous documentation standards for its Bash-based installer system. Understanding the **file header convention in ODS installer modules** is essential for contributors who need to create new phase scripts or library utilities that integrate with the automated installation harness. This convention ensures every module remains self-documenting and machine-readable without executing arbitrary code.

## The Three-Section Header Format

Every installer-related Bash script in the Osmantic/ODS codebase—whether a phase script or library utility—begins with a standardized three-section comment header. According to the Osmantic/ODS source code, each field appears as a hash-prefixed comment (`#`) at the very top of the file, following the shebang line.

The header uses the following structure:

- **Purpose**: A concise sentence describing what the script accomplishes.
- **Expects**: A comma-separated list of environment variables, inputs, or prerequisites required for execution.
- **Provides**: The outputs, side-effects, or exported values made available after successful execution.

This minimal structure deliberately avoids decorative comments, keeping modules lightweight and parseable by the installer harness.

## Implementation in Core ODS Files

The convention is consistently applied across the installer directory. In [`ods/installers/phases/01-preflight.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/01-preflight.sh), the header appears at lines 6–11, documenting the module's validation logic. Similarly, [`ods/installers/lib/ui.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/ui.sh) implements the same pattern at lines 6–12, declaring its user-interface helper functions.

These headers serve as explicit contracts: the **Expects** field tells the harness what variables must be populated before sourcing the file, while the **Provides** field indicates what state changes or variables the script guarantees on exit. This design enables the installer framework to validate inputs and outputs without executing the actual installation logic.

## Practical Examples for New Modules

When authoring a new installer phase or library script, replicate this exact layout starting immediately after the shebang. The following examples demonstrate the standard format used in [`ods/installers/phases/01-preflight.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/01-preflight.sh) and related utilities:

```bash
#!/usr/bin/env bash

# Purpose: Install Docker and Docker‑Compose on the host system.

# Expects: DRY_RUN, INTERACTIVE, LOG_FILE, SKIP_DOCKER

# Provides: DOCKER_CMD, DOCKER_COMPOSE_CMD

#

# (implementation follows...)

```

```bash
#!/usr/bin/env bash

# Purpose: Resolve the correct GPU‑specific docker‑compose overlay.

# Expects: SCRIPT_DIR, TIER, GPU_BACKEND, LOG_FILE

# Provides: COMPOSE_FILE, COMPOSE_FLAGS

#

# (implementation follows...)

```

Copy these templates directly when adding new phases to `ods/installers/phases/` or utility scripts to `ods/installers/lib/`.

## Machine Parsability and Automation

The strict **file header convention in ODS installer modules** exists primarily to support automated tooling. As implemented in Osmantic/ODS, the installer harness can source files and inspect these specific comment patterns to validate that all **Expects** variables are defined before execution and that all **Provides** values are generated afterward.

This machine-readable approach enables progress tracking, GUI integration, and static analysis without requiring static typing or complex manifest files. The convention ensures that [`ods/installers/phases/02-detection.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/02-detection.sh), [`ods/installers/lib/tier-map.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/tier-map.sh), and all other modules maintain a consistent, verifiable interface.

## Summary

- ODS installer modules use a standardized three-section header: **Purpose**, **Expects**, and **Provides**.
- Headers appear immediately after the shebang, using simple hash-prefixed comments (`# Field: value`).

- Files like [`ods/installers/phases/01-preflight.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/01-preflight.sh) (lines 6–11) and [`ods/installers/lib/ui.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/ui.sh) (lines 6–12) serve as canonical reference implementations.
- The convention enables the installer harness to validate inputs and outputs without executing scripts.
- New modules must follow this exact format to ensure compatibility with automated tooling and maintain consistency across the Osmantic/ODS codebase.

## Frequently Asked Questions

### What are the three required sections in an ODS installer header?

Every module must include **Purpose** (describing the script's function), **Expects** (listing required environment variables), and **Provides** (declaring exported outputs). These appear as the first three comments after the shebang line, as seen in [`ods/installers/phases/01-preflight.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/01-preflight.sh).

### Can I add decorative comments or additional fields to the header?

No. The convention deliberately avoids extra decorative comments to keep headers minimal and machine-parsable. The installer harness specifically looks for the three standard fields; additional commentary may interfere with automated parsing.

### How does the ODS installer harness use these headers?

The harness inspects the **Expects** and **Provides** fields to validate that all prerequisite environment variables are present before sourcing a script and to verify that declared outputs are generated after execution. This enables safe, non-executable validation of the installation contract.

### Where can I find reference implementations of the header convention?

Examine [`ods/installers/phases/01-preflight.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/01-preflight.sh) and [`ods/installers/lib/ui.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/ui.sh) in the Osmantic/ODS repository. These files demonstrate the standard layout at lines 6–11 and 6–12 respectively, providing working templates for new phase scripts and library utilities.