|
Bootstrap
Bash-based bootstrap engine reference documentation
|
This directory contains the Architecture Decision Records for the Bootstrap engine.
The ADRs collectively describe the project's architectural philosophy, long-term engineering decisions, and the reasoning behind those decisions. They are intended to answer a direct question:
Why is the project built this way?
Source code explains how the software works. Tests explain what behavior is expected. The ADRs explain why consequential architectural decisions were made and what alternatives were considered.
The linked ADR list below is generated from the current ADR corpus when reference documentation is built. The prose in this file is maintained source; the combined README.md used by Doxygen is generated and is not committed.
Although the ADRs are numbered chronologically, they are also organized around a set of recurring themes. Readers looking for answers to a specific question may find it useful to begin with the thematic groupings below and then use the linked index to open individual decisions.
These ADRs establish the project's goals, philosophy, and overall direction.
Topics include project philosophy, distribution, build process, release artifacts, and modular source organization.
These ADRs describe how the Bootstrap engine interprets user intent and performs work.
Topics include manifest interpretation, parsing, validation, execution planning, backend abstraction, and diagnostics.
These ADRs describe how users interact with the Bootstrap engine.
Topics include configuration, command-line interface, logging, exit codes, trust, and compatibility.
These ADRs describe how the project should evolve and how its engineering practices remain inspectable over time.
Topics include semantic versioning, architectural evolution, composition, testing, determinism, documentation, trusted computing base, contributor philosophy, package-installation safeguards, build and development dependencies, release artifact forms, threat modeling, and generated ADR navigation.
Across the collection, several ideas appear repeatedly.
The project consistently favors explicit user intent over implicit behavior, hidden discovery, or inferred configuration.
New capabilities should compose with existing architectural concepts rather than introducing special cases or redefining established behavior.
The project intentionally favors a small manifest language, a focused engine, and narrowly scoped responsibilities.
Externally visible behavior evolves deliberately and conservatively.
The project values inspectability, documentation, diagnostics, and predictable behavior because software that is easier to understand is easier to trust.
These documents are intended for several audiences. Users can understand what guarantees the project makes and why particular behaviors exist. Contributors should consult relevant ADRs before proposing architectural changes. Writers may use the records as source material for articles, presentations, or long-form writing about software architecture, engineering culture, and system design.
Automated tools should treat individual ADRs as atomic architectural decisions. The generated list above is navigation, not a substitute for reading the source records or doc/decisions.md when broader decision context is needed.
When deciding whether something deserves an ADR, ask whether it materially affects long-term architecture, whether future contributors would reasonably ask why the decision was made, and whether losing the rationale would make the project harder to understand.
If the decision primarily concerns implementation style, coding conventions, repository organization, or day-to-day workflow, contributor documentation is usually a better home.
The ADRs are the canonical record of architectural decisions. Other documents, including the project README, contributor guides, examples, current threat model, and architecture overviews, should summarize, organize, and reference these decisions rather than duplicate or replace them.
The repository's current STRIDE threat model remains maintained separately in doc/threat_model.md. Its Mermaid diagrams are not generated by this ADR index and are not replaced by this reference-documentation workflow.
Good architecture is more than a collection of correct technical decisions. It is a collection of decisions that remain understandable long after the implementation has changed. That is the purpose of this directory.
1.9.8