Skip to content

Commit e145f12

Browse files
josecelanojosecelano
committed
Merge #30: feat: add draft ADRs from PR #16 for review
64a6c62 feat: add draft ADRs from PR #16 (Cameron Garnham) Pull request description: This PR adds the draft ADRs from PR #16 to the `docs/adr/draft/` folder for review and potential integration. ## Changes - **ADR-009**: Proposal to Adopt a Modernized Automation Toolchain - **ADR-010**: Proposal for a Test-Driven Implementation and Structure - **ADR-011**: Proposal for Perl Coding and Security Standards - **ADR-012**: Proposal for Meson Build System Principles and Conventions ## Context These ADRs were originally proposed in PR #16 but were copied to avoid conflicts with the existing ADR sequence. They are placed in `docs/adr/draft/` for review and potential integration into the main ADR sequence. ## Author Attribution Original author: Cameron Garnham (@da2ce7) Extracted from: PR #16 ## Review Notes - ADRs have been renumbered from 004-007 to 009-012 to avoid conflicts - Internal cross-references have been updated to maintain consistency - Markdown lint issues have been fixed for better readability - Content remains unchanged from the original proposals Related to PR #16 ACKs for top commit: josecelano: ACK 64a6c62 Tree-SHA512: ccc33b16436af47647e793b925cbd46da8c92c422ea8a204dcfe70b9f8b7217d8ac26d7c968ad7a5da14e1dc1dfd73ec37683688d8f7b0fd37aea0b6203b3864
2 parents 8241fc7 + 64a6c62 commit e145f12

File tree

4 files changed

+419
-0
lines changed

4 files changed

+419
-0
lines changed

‎docs/adr/draft/009-adopt-modern-toolchain.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
### **ADR-009: Proposal to Adopt a Modernized Automation Toolchain**
2+
3+
- **Status:** Proposed for Review
4+
- **Date:** 2025-07-09
5+
- **Proposer:** Cameron
6+
- **Reviewers:** [List of project maintainers/core contributors]
7+
8+
#### **1. Context and Problem Statement**
9+
10+
The project's current automation toolchain, based on `Makefile` and POSIX-compliant shell
11+
scripts, has provided a simple and conventional interface for developers. It is pragmatic and
12+
effective for its stated purpose.
13+
14+
However, as we formally adopt the Twelve-Factor App methodology for the application itself, an
15+
analysis of our automation tooling reveals a philosophical misalignment. Specifically, the
16+
current tooling does not fully adhere to the principles it helps enforce:
17+
18+
1. **Implicit Dependencies (Violation of Factor II):** The toolchain implicitly relies on the
19+
existence and version of system-wide tools like `make`, `awk`, `grep`, and `curl`. Their
20+
presence is not explicitly declared or verified in a manifest, leading to a non-deterministic
21+
setup environment.
22+
2. **Blurred Build/Run Stages (Violation of Factor V):** Running a command like `make apply`
23+
mixes infrastructure planning, building, and execution. There is no distinct "build" or
24+
"setup" stage for the automation logic that validates its own dependencies before running.
25+
3. **Brittle Logic:** The current shell scripts rely on parsing the text output of command-line
26+
tools (e.g., `virsh domifaddr | awk ...`). This creates a fragile contract that is less
27+
stable across OS versions than using a formal, versioned API.
28+
29+
This proposal seeks to address these shortcomings by evolving our automation toolchain to be a
30+
first-class, Twelve-Factor-compliant component of the project, thereby increasing its long-term
31+
robustness and maintainability.
32+
33+
#### **2. Proposed Change**
34+
35+
It is proposed that the project adopt a new technology stack for its automation, based on the
36+
following core decisions:
37+
38+
1. **Adopt Meson as the Unified Automation Interface:** Meson will serve as the primary
39+
user-facing tool for running all project tasks. It will provide a single, declarative entry
40+
point for developers and CI/CD systems.
41+
2. **Adopt Modern Perl for Core Automation Logic:** The imperative logic currently in shell
42+
scripts will be migrated to a new, structured Perl codebase.
43+
3. **Adopt a "System-Package-Only" Dependency Policy:** To ensure maximum stability and a
44+
simple, curated "supply chain," this proposal mandates that all Perl module dependencies be
45+
fulfilled **exclusively through the system's native package manager** (e.g., `apt install
46+
libsys-virt-perl`). The direct use of language-specific, uncurated package managers like
47+
`cpanm` will be explicitly disallowed in the project's setup and CI workflows.
48+
4. **Establish a Stable Target Platform Benchmark:** All tooling and dependencies will target
49+
versions that are officially maintained for the **current Debian Stable release**. This
50+
includes packages from the official `backports` repository, as they are specifically compiled
51+
and certified for use with the stable base system. The critical guiding principle is: _Is the
52+
package officially provided for Debian Stable by the Debian maintainers?_
53+
- _As of this writing, this sets our target versions to **Perl `5.36.0`** (from `bookworm`)
54+
and **Meson `1.7.0`** (from `bookworm-backports`)._
55+
56+
#### **3. Rationale for Proposed Change**
57+
58+
This strategic evolution will bring our automation toolchain into stronger alignment with the
59+
Twelve-Factor methodology and yield significant long-term benefits:
60+
61+
- **Explicit, Verifiable Dependencies (Factor II):** The `meson.build` file will serve as an
62+
explicit dependency manifest. It will programmatically check for `perl`, `opentofu`,
63+
`libvirt-client`, and all required `perl-*` packages. This provides a single, deterministic
64+
command (`meson setup`) to validate a contributor's environment, failing hard and early with
65+
clear error messages if the environment is incorrect.
66+
- **Clear Build/Run Separation (Factor V):** The Meson workflow naturally separates our
67+
processes. `meson setup` becomes our distinct "build" stage, which configures the project and
68+
validates all dependencies. `meson test` or `meson compile` becomes the "run" stage,
69+
executing tasks in a pre-validated environment.
70+
- **Increased Robustness and Maintainability:** Migrating from brittle text-parsing in shell to
71+
using formal Perl modules (like `Sys::Virt`) allows us to depend on more stable, versioned
72+
APIs. Perl also provides superior error handling, data structures, and code organization,
73+
which will make the automation easier to maintain and extend.
74+
75+
#### **4. Scope and Relationship to Other Proposals**
76+
77+
This document's scope is strictly limited to the **strategic decision to adopt Meson and
78+
Perl**. It establishes the core "why" and "what" of the change.
79+
80+
All further details are explicitly deferred to subsequent proposals, which will build upon this
81+
foundational decision:
82+
83+
- **Implementation Strategy & Structure (`ADR-005`):** Will detail the "how" of this migration,
84+
including the specific repository structure, the plan for an atomic cutover (a "flag day"
85+
migration), and the deprecation of the `Makefile`.
86+
- **Coding & Quality Standards (`ADR-006` and `ADR-007`):** Will define the "rules of the road"
87+
for the new Perl and Meson codebase, including mandatory pragmas, security hardening, linting
88+
policies, and style conventions.
89+
90+
#### **5. Consequences and Acknowledged Trade-offs**
91+
92+
- **Primary Benefit:** The project's automation tooling will become a more reliable,
93+
maintainable, and professionally engineered component, in full alignment with the principles
94+
it helps to deploy.
95+
- **Acknowledged Trade-off 1: Loss of "Zero-Prerequisite" Setup.** The single greatest
96+
trade-off is sacrificing the convenience of `make` being pre-installed. A contributor's first
97+
action will now be to install the Meson/Perl toolchain via their system package manager. This
98+
is a conscious decision to prioritize explicit, verifiable correctness over "zero-setup"
99+
convenience.
100+
- **Acknowledged Trade-off 2: Dependency on a Curated Ecosystem.** By committing to system
101+
packages benchmarked against Debian Stable (including its official backports), we gain
102+
stability at the cost of immediate access to bleeding-edge tool and library features. This is
103+
a deliberate choice to favor long-term stability and reliability.
104+
105+
#### **6. Next Steps**
106+
107+
If this strategic proposal is accepted, the maintainers will proceed with a formal review of
108+
`ADR-005`, `ADR-006`, and `ADR-007` to finalize the implementation plan and quality standards
109+
for the new toolchain.

‎docs/adr/draft/010-test-driven-implementation.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
### **ADR-010: Proposal for a Test-Driven Implementation and Structure**
2+
3+
- **Status:** Proposed for Review
4+
- **Date:** 2025-07-09
5+
- **Proposer:** Cameron
6+
- **Reviewers:** [List of project maintainers/core contributors]
7+
- **Depends On:** [ADR-009: Proposal to Adopt a Modernized Automation Toolchain](./009-adopt-modern-toolchain.md)
8+
- **Supersedes:** [ADR-001: Keep Makefile at Repository Root Level](./001-makefile-location.md)
9+
10+
#### **1. Context and Problem Statement**
11+
12+
Following the strategic decision in `ADR-004` to adopt a Meson/Perl toolchain, we must now
13+
define a concrete implementation plan. A simple one-to-one replacement of scripts would fail to
14+
capitalize on the full benefits of the new toolchain and could lead to a disorganized codebase.
15+
16+
This proposal addresses the "how" and "where" of the migration. It recommends a specific code
17+
structure and implementation methodology designed to maximize the reliability, maintainability,
18+
and testability of our new automation system. It also proposes an atomic migration strategy to
19+
ensure a clean and unambiguous transition.
20+
21+
#### **2. Proposed Change**
22+
23+
It is proposed that the new toolchain be implemented using the following structured approach:
24+
25+
1. **Centralize Automation Logic:** A new top-level `automation/` directory will be created.
26+
This directory will become the single, authoritative home for all imperative automation code
27+
(Perl scripts and modules) and their corresponding tests. This cleanly separates the
28+
project's declarative artifacts (in `infrastructure/` and `application/`) from the
29+
imperative code that acts upon them.
30+
31+
2. **Adopt a Test-Driven Standard:** All new Perl logic will be accompanied by a formal test
32+
suite located in `automation/t/`. The project's primary test command, `meson test`, will
33+
validate the correctness of the automation logic itself, enabling unit tests that can run
34+
without requiring a live, deployed environment.
35+
36+
3. **Execute an Atomic "Flag Day" Migration:** The transition from the legacy `Makefile`/`sh`
37+
system will be performed in a single, comprehensive changeset. This "clean break" approach
38+
avoids a confusing transitional period with two competing systems. The `Makefile` and old
39+
scripts will be removed entirely, and the Meson/Perl system will be introduced as the sole,
40+
official standard.
41+
42+
#### **3. Proposed Repository Structure**
43+
44+
The following structure is recommended to support this change. It is designed for clarity and a
45+
strong separation of concerns.
46+
47+
```text
48+
torrust-tracker-demo/
49+
├── application/ # Application deployment artifacts (e.g., compose.yaml)
50+
├── infrastructure/ # Infrastructure-as-Code declarations (Terraform, cloud-init)
51+
├── docs/ # Project documentation
52+
├── automation/ # NEW: All automation logic and its tests
53+
│ ├── lib/ # Reusable Perl modules (e.g., Torrust::Demo::*)
54+
│ ├── t/ # Test suite for automation logic (*.t files)
55+
│ └── meson.build # Defines all automation targets
56+
├── .gitignore
57+
└── meson.build # ROOT INTERFACE: Orchestrates all tasks
58+
```
59+
60+
#### **4. Rationale for Proposed Change**
61+
62+
This structured and test-driven approach is recommended because it allows us to build a truly
63+
professional-grade automation toolchain:
64+
65+
- **Reliability Through Testing:** Implementing a test suite for our automation code is a
66+
transformative step. It allows us to verify complex logic (e.g., parsing configuration,
67+
generating template files) in isolation, leading to fewer bugs and faster, more confident
68+
development of our tooling.
69+
- **Improved Maintainability:** The proposed structure creates a clear "home" for all automation
70+
code. This makes the system easier for new contributors to understand and easier for
71+
maintainers to extend. Separating logic into reusable Perl modules (`.pm` files) will reduce
72+
code duplication and improve overall quality.
73+
- **Clarity of Implementation:** An atomic migration, while disruptive, provides immediate and
74+
total clarity. There is no ambiguity about which system to use or how tasks should be run. All
75+
documentation and workflows can be updated to reflect a single, consistent standard from day
76+
one.
77+
78+
#### **5. Scope and Relationship to Other Proposals**
79+
80+
This document's scope is strictly limited to the **implementation strategy, repository
81+
structure, and testing philosophy** of the new toolchain. It defines the "how" and "where" of
82+
the migration.
83+
84+
It explicitly defers the definition of specific coding conventions to the next document:
85+
86+
- **Coding & Quality Standards (`ADR-006`):** Will define the specific rules for the Perl code
87+
itself, such as mandatory pragmas (`use strict;`), security hardening (`-T`), and static
88+
analysis (`Perl::Critic`) policies.
89+
90+
#### **6. Acknowledged Trade-offs**
91+
92+
- **One-Time Contributor Effort:** The primary trade-off is that an atomic migration requires
93+
every contributor to learn and adapt to the new `meson`-based workflow simultaneously. The
94+
legacy `make` commands they are familiar with will cease to exist.
95+
- **Mitigation Strategy:** This cost is deemed acceptable for the long-term benefit of a single,
96+
superior system. The migration will be supported by a comprehensive update to all
97+
documentation (`README.md`, contributing guides) and clear project-level communication to
98+
prepare contributors for the change.
99+
100+
#### **7. Next Steps**
101+
102+
If this proposal for the implementation strategy is accepted, the maintainers will proceed with
103+
a final review of `ADR-006` to establish the formal coding standards before beginning the
104+
migration work outlined herein.

‎docs/adr/draft/011-perl-coding-standards.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
### **ADR-011: Proposal for Perl Coding and Security Standards**
2+
3+
- **Status:** Proposed for Review
4+
- **Date:** 2025-07-09
5+
- **Proposer:** Cameron
6+
- **Reviewers:** [List of project maintainers/core contributors]
7+
- **Depends On:** [ADR-010: Proposal for a Test-Driven Implementation and Structure](./010-test-driven-implementation.md)
8+
9+
#### **1. Context and Problem Statement**
10+
11+
Having established the strategy (`ADR-004`) and structure (`ADR-005`) for our new Meson/Perl
12+
automation toolchain, it is imperative that we define a clear and enforceable set of standards
13+
for the code itself. Without agreed-upon conventions, the new codebase could quickly accumulate
14+
technical debt, becoming inconsistent, insecure, or difficult to maintain.
15+
16+
This proposal aims to establish a baseline of quality, security, and convention for all Perl
17+
code within the `automation/` directory, ensuring the long-term health and clarity of our
18+
internal tooling.
19+
20+
#### **2. Proposed Standards**
21+
22+
It is proposed that the project adopt the following set of standards for all Perl code
23+
contributed:
24+
25+
1. **Mandatory Pragmas for Code Safety:** It is recommended that all Perl scripts (`.pl`) and
26+
modules (`.pm`) enable `use strict;`, `use warnings;`, and `use autodie;`. This combination
27+
is foundational for modern, safe Perl, as it catches common errors, enforces good scoping,
28+
and ensures that failed system calls result in a predictable, immediate script failure.
29+
30+
2. **Minimum Perl Version Benchmark:** To ensure broad compatibility and stability, it is
31+
proposed that the codebase target the version of Perl shipped in the **current Debian Stable
32+
release**. This provides an objective benchmark that aligns development with common server
33+
environments. The corresponding `use vX.XX;` pragma should be included in all Perl files to
34+
enforce this minimum version.
35+
36+
- _As of this writing, Debian 12 ("Bookworm") ships with Perl 5.36.0. The current standard
37+
would therefore be **`use v5.36;`**._
38+
39+
3. **Static Analysis via Perl::Critic:** It is suggested that `Perl::Critic` be adopted as the
40+
official linter. By integrating it into the `meson test` suite, we can provide automated
41+
feedback on code style and quality for all contributions, ensuring consistency.
42+
43+
4. **Security Hardening by Default:** It is recommended that all executable Perl scripts be run
44+
with taint mode (`-T`). This is a proven security feature that prevents insecure data passed
45+
from outside the program (e.g., environment variables, command-line arguments) from being
46+
used in commands that interact with the shell.
47+
48+
5. **Consistent Command-Line Interface:** To create a predictable user experience for
49+
developers, it is proposed that all public-facing scripts adopt a standard CLI argument
50+
style, implemented using Perl's core `Getopt::Long` module.
51+
52+
#### **3. Rationale for Proposed Standards**
53+
54+
Adopting this comprehensive set of standards offers clear, long-term engineering advantages:
55+
56+
- **Reliability:** The chosen pragmas create code that is robust by default. `autodie` ensures
57+
that a failed `open()` or `mkdir()` will halt execution immediately, which is critical for
58+
deterministic automation.
59+
- **Security:** Taint mode (`-T`) provides a strong, language-level defense against a class of
60+
command-injection vulnerabilities, which is a professional standard for any tool that
61+
orchestrates system commands.
62+
- **Maintainability:** A consistent style enforced by `Perl::Critic` reduces the cognitive
63+
overhead required to read, review, and maintain the codebase. Code reviews can focus on logic,
64+
not formatting.
65+
- **Stability:** Pegging the language version to Debian Stable provides a durable and predictable
66+
platform, avoiding both rapid churn from chasing the latest features and stagnation from
67+
targeting old versions.
68+
69+
#### **4. Recommended Implementation**
70+
71+
**1. Standard Boilerplate for `.pl` and `.pm` files:**
72+
The following header could serve as a template for all new Perl files.
73+
74+
```perl
75+
#!/usr/bin/env perl -T
76+
# The -T flag enables taint mode for security hardening.
77+
78+
use strict;
79+
use warnings;
80+
# The autodie pragma automatically promotes failed system calls into exceptions.
81+
use autodie;
82+
83+
# Enforce a minimum Perl version pegged to the current Debian Stable release.
84+
# As of Q3 2025, this is Perl 5.36 (from Debian 12 'Bookworm').
85+
use v5.36;
86+
```
87+
88+
**2. Centralized `Perl::Critic` Configuration:**
89+
To manage our linting policy, a configuration file should be created at `automation/.perlcriticrc`.
90+
91+
```ini
92+
# A gentle starting point that focuses on the most important issues.
93+
# It avoids being overly pedantic about minor style nits.
94+
severity = gentle
95+
96+
# Example of disabling a specific, often-controversial policy.
97+
# Subroutine prototypes are used less often in modern Perl styles.
98+
[-Subroutines::ProhibitSubroutinePrototypes]
99+
```
100+
101+
**3. Proposed Meson Integration:**
102+
The `meson.build` file can define clear, separate targets for testing and linting.
103+
104+
```meson
105+
# In meson.build
106+
107+
perlcritic_prog = find_program('perlcritic', required: true)
108+
prove_prog = find_program('prove', required: true)
109+
110+
# Test Target 1: Code Style & Quality. Implicitly uses .perlcriticrc.
111+
test('Perl::Critic Linting', perlcritic_prog, args: ['automation/'])
112+
113+
# Test Target 2: Unit Test Execution via the 'prove' TAP harness.
114+
test('Automation Unit Tests', prove_prog, args: ['-vr', 'automation/t/'])
115+
```
116+
117+
#### **5. Acknowledged Trade-offs**
118+
119+
- **Increased Formality:** This proposal introduces a more formal development process.
120+
Contributors will need to adhere to these standards, which is more restrictive than writing
121+
simple shell scripts. This is presented as a beneficial trade-off for the gains in long-term
122+
quality and security.
123+
- **Exclusion of Newer Language Features:** The project would intentionally be unable to use
124+
Perl features newer than what is available in the benchmarked Debian Stable release. This is a
125+
deliberate choice prioritizing stability and compatibility.
126+
127+
#### **6. Next Steps**
128+
129+
If this proposal is accepted, it will serve as the official quality standard for all code
130+
developed during the migration outlined in `ADR-005`. All new Perl contributions will be
131+
expected to adhere to these rules, which will be enforced automatically by the CI pipeline.

0 commit comments

Comments
 (0)