daniel/ansible-bind9-role
1
0
Fork 0
Code Issues 3 Pull Requests 2 Actions Projects Releases Wiki Activity

docs: Clarify implemented vs planned features for BIND9 9.20 support #15

New Issue
Open
opened 2026-02-07 23:08:23 +00:00 by daniel · 3 comments
daniel commented 2026-02-07 23:08:23 +00:00
Owner
Copy Link
Copy Source

Description

The docs/BIND9_9.20_SUPPORT.md documentation includes sections describing runtime version detection and template conditionals that are planned features rather than currently implemented functionality.

Current Issue

Users reading the documentation may expect:

  • bind9_version variable to be automatically set at runtime
  • Template conditionals to handle version-specific configurations
  • Version detection code examples in tasks/main.yml

However, the actual implementation strategy uses versioned branches instead:

  • main branch: BIND9 9.18.x (LTS) - hardcoded for 9.18.x
  • 9.20 branch: BIND9 9.20+ - hardcoded for 9.20+
  • No runtime version detection needed
  • No template conditionals required

Solution

Update documentation to:

  1. Clarify that versioned branches approach eliminates need for runtime detection
  2. Move "Implementation Details" section to "Planned Future Enhancements" if runtime detection becomes needed
  3. Add note explaining why branch-per-version is preferred
  4. Document the versioned branch strategy more clearly
  5. Update task/main.yml section to reference actual current implementation

Related Issues

  • PR #14: Comments explaining this design decision

Tasks

  • Update docs/BIND9_9.20_SUPPORT.md to clarify versioned branch strategy
  • Add section explaining why runtime detection is not implemented
  • Update "Implementation Details" to show actual current code structure
  • Add future enhancements section if runtime detection is ever needed
  • Review other docs for similar clarity issues
## Description The docs/BIND9_9.20_SUPPORT.md documentation includes sections describing runtime version detection and template conditionals that are planned features rather than currently implemented functionality. ## Current Issue Users reading the documentation may expect: - `bind9_version` variable to be automatically set at runtime - Template conditionals to handle version-specific configurations - Version detection code examples in tasks/main.yml However, the actual implementation strategy uses **versioned branches** instead: - `main` branch: BIND9 9.18.x (LTS) - hardcoded for 9.18.x - `9.20` branch: BIND9 9.20+ - hardcoded for 9.20+ - No runtime version detection needed - No template conditionals required ## Solution Update documentation to: 1. Clarify that versioned branches approach eliminates need for runtime detection 2. Move "Implementation Details" section to "Planned Future Enhancements" if runtime detection becomes needed 3. Add note explaining why branch-per-version is preferred 4. Document the versioned branch strategy more clearly 5. Update task/main.yml section to reference actual current implementation ## Related Issues - PR #14: Comments explaining this design decision ## Tasks - [ ] Update docs/BIND9_9.20_SUPPORT.md to clarify versioned branch strategy - [ ] Add section explaining why runtime detection is not implemented - [ ] Update "Implementation Details" to show actual current code structure - [ ] Add future enhancements section if runtime detection is ever needed - [ ] Review other docs for similar clarity issues
daniel commented 2026-07-02 07:40:29 +00:00
Author
Owner
Copy Link
Copy Source

Design Spec: Clarify BIND9 9.20 Implemented vs Planned Features

Objective

Resolve the documentation and metadata mismatch where the role currently describes runtime BIND9 version detection and template conditionals as implemented behavior, while the actual project strategy is versioned branches.

Current Problem

docs/BIND9_9.20_SUPPORT.md, docs/VERSION_SUPPORT.md, and meta/argument_specs.yml contain user-facing claims that imply:

  • bind9_version is automatically detected at runtime.
  • Templates use runtime version conditionals to choose BIND9 9.18 vs 9.20 behavior.
  • tasks/main.yml contains or should contain version detection logic.

The actual implementation does not set bind9_version, does not use version-aware template conditionals, and keeps BIND9 compatibility boundaries at the branch level:

  • main: BIND9 9.18.x LTS behavior.
  • 9.20: BIND9 9.20+ behavior.

Selected Approach

Make a documentation and argument-spec correction only. Do not implement runtime version detection as part of this issue.

This is preferred because issue #15 is about making documentation truthful, and the branch-per-version strategy is the documented design decision from prior PR discussion. Adding runtime detection would be a behavior change with broader test and compatibility implications.

Files In Scope

  • docs/BIND9_9.20_SUPPORT.md
  • docs/VERSION_SUPPORT.md
  • meta/argument_specs.yml

Required Changes

  1. Reframe docs/BIND9_9.20_SUPPORT.md so the current implementation strategy is branch-per-version, not runtime detection plus conditionals.
  2. Replace the current runtime detection example under implementation details with the real current task flow:
    • install configured BIND9 packages,
    • ensure needed directories exist,
    • render configured files with named.conf.generator.j2,
    • validate using named-checkconf,
    • restore from backup on validation failure,
    • start and enable the named service.
  3. Add a short explanation for why runtime version detection is not implemented:
    • compatibility boundaries are clearer,
    • templates avoid cross-version conditional complexity,
    • each branch can be tested against its intended BIND9 series,
    • users do not get silent rendering behavior based on detected package versions.
  4. Move runtime version detection and template conditionals into future enhancements only, phrased as optional future work if branch-per-version maintenance becomes insufficient.
  5. Update docs/VERSION_SUPPORT.md so its version-specific features section no longer presents runtime detection as the planned/current strategy. It should instead describe branch-level version targeting and mention runtime detection only as a possible future alternative.
  6. Update meta/argument_specs.yml to remove the false public interface around bind9_version. Since the role does not set this variable or use it in templates, it should not be documented as an auto-detected, read-only option.

Out of Scope

  • No changes to role behavior.
  • No runtime version detection implementation.
  • No template conditionals for BIND9 version selection.
  • No new Molecule scenarios or CI matrix work.
  • No release tagging.

Validation

Validation should be lightweight and focused on this documentation/metadata fix:

  • Search for stale claims such as Version detection is automatic at runtime, bind9_version, Runtime Version Detection, and Template Conditionals.
  • Confirm any remaining mentions are clearly framed as future-only, not current implementation.
  • Validate edited YAML syntax for meta/argument_specs.yml.
  • Run markdown/YAML lint if available locally; otherwise document that only syntax/search validation was run.

Acceptance Criteria

  • Users reading the BIND9 9.20 support docs understand that versioned branches are the current strategy.
  • The docs no longer imply that tasks/main.yml performs runtime version detection.
  • meta/argument_specs.yml no longer advertises bind9_version as auto-detected behavior.
  • Runtime detection and template conditionals, if still mentioned, are explicitly future-only alternatives.
  • No role behavior changes are included in the fix.
## Design Spec: Clarify BIND9 9.20 Implemented vs Planned Features ### Objective Resolve the documentation and metadata mismatch where the role currently describes runtime BIND9 version detection and template conditionals as implemented behavior, while the actual project strategy is versioned branches. ### Current Problem `docs/BIND9_9.20_SUPPORT.md`, `docs/VERSION_SUPPORT.md`, and `meta/argument_specs.yml` contain user-facing claims that imply: - `bind9_version` is automatically detected at runtime. - Templates use runtime version conditionals to choose BIND9 9.18 vs 9.20 behavior. - `tasks/main.yml` contains or should contain version detection logic. The actual implementation does not set `bind9_version`, does not use version-aware template conditionals, and keeps BIND9 compatibility boundaries at the branch level: - `main`: BIND9 9.18.x LTS behavior. - `9.20`: BIND9 9.20+ behavior. ### Selected Approach Make a documentation and argument-spec correction only. Do not implement runtime version detection as part of this issue. This is preferred because issue #15 is about making documentation truthful, and the branch-per-version strategy is the documented design decision from prior PR discussion. Adding runtime detection would be a behavior change with broader test and compatibility implications. ### Files In Scope - `docs/BIND9_9.20_SUPPORT.md` - `docs/VERSION_SUPPORT.md` - `meta/argument_specs.yml` ### Required Changes 1. Reframe `docs/BIND9_9.20_SUPPORT.md` so the current implementation strategy is branch-per-version, not runtime detection plus conditionals. 2. Replace the current runtime detection example under implementation details with the real current task flow: - install configured BIND9 packages, - ensure needed directories exist, - render configured files with `named.conf.generator.j2`, - validate using `named-checkconf`, - restore from backup on validation failure, - start and enable the `named` service. 3. Add a short explanation for why runtime version detection is not implemented: - compatibility boundaries are clearer, - templates avoid cross-version conditional complexity, - each branch can be tested against its intended BIND9 series, - users do not get silent rendering behavior based on detected package versions. 4. Move runtime version detection and template conditionals into future enhancements only, phrased as optional future work if branch-per-version maintenance becomes insufficient. 5. Update `docs/VERSION_SUPPORT.md` so its version-specific features section no longer presents runtime detection as the planned/current strategy. It should instead describe branch-level version targeting and mention runtime detection only as a possible future alternative. 6. Update `meta/argument_specs.yml` to remove the false public interface around `bind9_version`. Since the role does not set this variable or use it in templates, it should not be documented as an auto-detected, read-only option. ### Out of Scope - No changes to role behavior. - No runtime version detection implementation. - No template conditionals for BIND9 version selection. - No new Molecule scenarios or CI matrix work. - No release tagging. ### Validation Validation should be lightweight and focused on this documentation/metadata fix: - Search for stale claims such as `Version detection is automatic at runtime`, `bind9_version`, `Runtime Version Detection`, and `Template Conditionals`. - Confirm any remaining mentions are clearly framed as future-only, not current implementation. - Validate edited YAML syntax for `meta/argument_specs.yml`. - Run markdown/YAML lint if available locally; otherwise document that only syntax/search validation was run. ### Acceptance Criteria - Users reading the BIND9 9.20 support docs understand that versioned branches are the current strategy. - The docs no longer imply that `tasks/main.yml` performs runtime version detection. - `meta/argument_specs.yml` no longer advertises `bind9_version` as auto-detected behavior. - Runtime detection and template conditionals, if still mentioned, are explicitly future-only alternatives. - No role behavior changes are included in the fix.
daniel commented 2026-07-02 07:43:47 +00:00
Author
Owner
Copy Link
Copy Source

Issue #15 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make the BIND9 9.20 documentation and role argument metadata accurately describe the current branch-per-version strategy, without changing role behavior.

Architecture: This is a documentation/metadata-only change. docs/BIND9_9.20_SUPPORT.md becomes the specific implementation guide for branch-based 9.20 support, docs/VERSION_SUPPORT.md keeps the broader version policy aligned with that strategy, and meta/argument_specs.yml stops advertising a bind9_version variable that the role does not set or consume.

Tech Stack: Markdown, YAML, Ansible role metadata, local shell validation with rg, Python YAML parsing or yamllint if available.

File Structure

  • Modify: docs/BIND9_9.20_SUPPORT.md
    • Responsibility: Explain the BIND9 9.20 support strategy and implementation status. Current behavior must be branch-per-version. Runtime detection must be future-only.
  • Modify: docs/VERSION_SUPPORT.md
    • Responsibility: Define the version support policy. It must not describe runtime detection as current or planned implementation for the active branch strategy.
  • Modify: meta/argument_specs.yml
    • Responsibility: Document the public role interface. It must not expose bind9_version as auto-detected behavior because no task sets it and no template uses it.

No new files are required.

Task 1: Prepare Branch And Capture Baseline

Files:

  • Read: docs/BIND9_9.20_SUPPORT.md

  • Read: docs/VERSION_SUPPORT.md

  • Read: meta/argument_specs.yml

  • Read: tasks/main.yml

  • Step 1: Create a ticket branch

Run:

git switch -c fix/issue-15-bind920-docs-strategy

Expected: branch changes to fix/issue-15-bind920-docs-strategy.

  • Step 2: Confirm only known untracked local files exist before editing

Run:

git status --short

Expected: only pre-existing untracked local workspace files such as .ansible/ and .vscode/, or a clean tree. Do not add those untracked local directories.

  • Step 3: Capture stale runtime-detection claims

Run:

rg -n "Runtime Version Detection|Template Conditionals|bind9_version|Version detection is automatic at runtime|tasks/main.yml \(planned implementation\)|Templates will use version-aware conditionals" docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml

Expected before editing: matches in all three files, including docs/BIND9_9.20_SUPPORT.md, docs/VERSION_SUPPORT.md, and meta/argument_specs.yml.

Task 2: Correct docs/BIND9_9.20_SUPPORT.md

Files:

  • Modify: docs/BIND9_9.20_SUPPORT.md

  • Step 1: Replace the overview, architecture, branch, and implementation sections

Apply this patch:

diff --git a/docs/BIND9_9.20_SUPPORT.md b/docs/BIND9_9.20_SUPPORT.md
--- a/docs/BIND9_9.20_SUPPORT.md
+++ b/docs/BIND9_9.20_SUPPORT.md
@@
-This document describes the ansible-bind9-role implementation for BIND9 9.20+ support through the `feature/bind9-20-support` branch.
+This document describes the ansible-bind9-role strategy for BIND9 9.20+ support through a dedicated version branch.
+
+The current implementation uses branch-level compatibility boundaries instead of runtime version detection. The `main` branch targets BIND9 9.18.x LTS, while the `9.20` branch targets BIND9 9.20+ feature releases.
@@
-The role supports multiple BIND9 versions using:
-
-1. **Runtime Version Detection**: BIND9 version is detected at runtime and stored in the `bind9_version` fact
-2. **Template Conditionals**: Jinja2 conditionals in templates apply version-specific configurations
-3. **Separate Branches**: Different BIND9 feature release series are maintained on separate branches
-   - `main`: BIND9 9.18.x (LTS) - Production stable
-   - `9.20`: BIND9 9.20+ (feature releases) - New features and modern approach
+The role supports multiple BIND9 versions with separate branches:
+
+1. **`main` branch**: BIND9 9.18.x LTS support for production-stable deployments.
+2. **`9.20` branch**: BIND9 9.20+ feature-release support with version-specific templates, grammar data, tests, and documentation.
+
+The role does not currently detect BIND9 versions at runtime and does not use runtime version conditionals in templates. Each branch is expected to be tested against the BIND9 series it supports.
+
+This approach is preferred because:
+
+- compatibility boundaries are clear for users and maintainers;
+- templates avoid cross-version conditional complexity;
+- each branch can evolve with the grammar and package behavior of its target BIND9 series;
+- generated configuration does not silently change based on the installed package version.
@@
-main                          # BIND9 9.18.x LTS (stable)
-│
-└─ 9.20                       # BIND9 9.20+ feature releases
-   ├─ feature/bind9-20-support  # Current development branch
-   └─ (will merge to 9.20 after testing)
+main                    # BIND9 9.18.x LTS support
+│
+└─ 9.20                 # BIND9 9.20+ feature-release support
+   └─ feature/*          # Short-lived feature branches targeting 9.20

Implementation Details

-### 1. Version Detection (tasks/main.yml)

-```yaml
-- name: Detect BIND9 version at runtime

  • ansible.builtin.command:
  • cmd: named -v
  • register: _bind9_version_output
  • changed_when: false

-- name: Set bind9_version fact

  • ansible.builtin.set_fact:
  • bind9_version: "{{ _bind9_version_output.stdout | regex_search('BIND (\S+)', '\1') | first }}"
    -```

-### 2. Meta/Argument Specs Updates

-The meta/argument_specs.yml has been updated to:

-- Document BIND9 9.20+ support alongside 9.18.x
-- Add bind9_version variable documentation (read-only, auto-detected)
-- Clarify version-specific behavior

-### 3. Molecule Testing
+### 1. Current Role Task Flow
+
+The role currently follows the same task structure on each version branch:
+
+1. Install the configured BIND9 packages from bind9_packages.
+2. Ensure backup and logging directories exist when enabled or configured.
+3. Render configured BIND9 files through named.conf.generator.j2.
+4. Validate the generated configuration with named-checkconf -z.
+5. Restore backed-up configuration files if validation fails.
+6. Start and enable the named service.
+
+There is no runtime bind9_version fact in this flow.
+
+### 2. Meta/Argument Specs
+
+The meta/argument_specs.yml file documents the public role inputs for the current branch. It must not document runtime-only variables that the role does not set or consume.
+
+### 3. Molecule Testing
@@
-### 4. Template Version Compatibility
+### 4. Template Version Compatibility
@@
-Templates have been audited for BIND9 9.20 compatibility. The primary template files include:
+Templates in each version branch should be audited for the BIND9 series targeted by that branch. The primary template files include:
@@
-### 5. Deprecated Options Handling
+### 5. Deprecated Options Handling
@@
-BIND9 9.20 removes 44 options from 9.18. The role handles this through:
+BIND9 9.20 removes 44 options from 9.18. The 9.20 branch should handle this through:

  1. Documentation: Each deprecated option is documented in BIND9_MIGRATION_GUIDE.md
    -2. Conditional Removal: Templates check version and exclude removed options
    +2. Branch-specific templates: Templates on the 9.20 branch omit removed options
  2. Migration Path: BIND9_MIGRATION_GUIDE.md provides alternatives for each removed option

- [ ] **Step 2: Reframe future enhancements**

In `docs/BIND9_9.20_SUPPORT.md`, update the `## Future Enhancements` list so it includes runtime detection only as a future alternative. The resulting list must include these items exactly:

```markdown
## Future Enhancements

- [ ] Automated configuration migration tool
- [ ] Deprecation warnings in role output
- [ ] Runtime version detection if branch-per-version maintenance becomes insufficient
- [ ] Template conditionals only if a future design intentionally supports multiple BIND9 series from one branch
- [ ] 9.21+ preparation when available
- [ ] Performance tuning for 9.20 features
- [ ] DNS-over-HTTPS (DoH) support
- [ ] Clustering/high-availability examples
  • Step 3: Verify the document no longer presents runtime detection as current

Run:

rg -n "Runtime Version Detection|Template Conditionals|bind9_version|detected at runtime|Conditional Removal|Templates check version" docs/BIND9_9.20_SUPPORT.md

Expected after editing: no matches except acceptable future-only wording for runtime detection/template conditionals. If a match implies current behavior, revise it before continuing.

Task 3: Correct docs/VERSION_SUPPORT.md

Files:

  • Modify: docs/VERSION_SUPPORT.md

  • Step 1: Replace the version-specific features section

Replace the section from ## Version-Specific Features through the end of the ### Conditional Configuration subsection with this content:

## Version-Specific Features

### Branch-Level Version Targeting

The role currently uses branch-level version targeting instead of runtime version detection:

- `main` targets BIND9 9.18.x LTS.
- `9.20` targets BIND9 9.20+ feature releases.

Each branch carries the templates, grammar data, documentation, and tests appropriate for its supported BIND9 series. This keeps generated configuration predictable and avoids mixing incompatible BIND9 grammar rules in one template path.

### Runtime Detection

Runtime version detection is not part of the current implementation. The role does not set `bind9_version_full`, `bind9_version_major`, `bind9_version_minor`, or `bind9_version`, and templates do not branch on those values.

Runtime detection may be reconsidered in the future if maintaining separate version branches becomes more expensive than supporting multiple BIND9 series from one branch. That future design would require dedicated tasks, public metadata, template changes, and Molecule coverage before being documented as supported behavior.
  • Step 2: Verify the policy no longer includes planned runtime-detection code examples

Run:

rg -n "tasks/main.yml \(planned implementation\)|bind9_version_full|bind9_version_major|bind9_version_minor|Templates will use version-aware conditionals|templates/named.conf.options.j2 \(planned\)" docs/VERSION_SUPPORT.md

Expected after editing: no output.

Task 4: Correct meta/argument_specs.yml

Files:

  • Modify: meta/argument_specs.yml

  • Step 1: Remove false runtime-detection wording from the role description

Change the argument_specs.main.description block from:

    description:
      - Configures BIND9 DNS server on Debian-based systems.
      - "Supported BIND9 versions: 9.18.x (LTS), 9.20+ (feature releases)"
      - Version detection is automatic at runtime.

to:

    description:
      - Configures BIND9 DNS server on Debian-based systems.
      - "Supported BIND9 versions are branch-specific: main targets 9.18.x (LTS), and the 9.20 branch targets 9.20+ feature releases."
  • Step 2: Remove the unsupported bind9_version option

Delete this option block entirely:

      bind9_version:
        type: str
        description:
          - BIND9 version detected at runtime (read-only, set automatically).
          - "Format: X.Y.Z (e.g., 9.18.44, 9.20.18)"
          - Used by templates to apply version-specific configurations.
          - Users should not set this variable directly.
  • Step 3: Validate YAML syntax

Run:

python3 - <<'PY'
from pathlib import Path
import yaml
for path in [Path('meta/argument_specs.yml')]:
    yaml.safe_load(path.read_text())
    print(f'OK {path}')
PY

Expected:

OK meta/argument_specs.yml

If PyYAML is not installed, run this fallback:

python3 - <<'PY'
from pathlib import Path
path = Path('meta/argument_specs.yml')
text = path.read_text()
assert 'bind9_version:' not in text
assert 'Version detection is automatic at runtime.' not in text
print(f'OK {path}')
PY

Expected:

OK meta/argument_specs.yml

Task 5: Run Focused Validation

Files:

  • Read: docs/BIND9_9.20_SUPPORT.md

  • Read: docs/VERSION_SUPPORT.md

  • Read: meta/argument_specs.yml

  • Step 1: Search for stale current-behavior claims

Run:

rg -n "Version detection is automatic at runtime|BIND9 version is detected at runtime|stored in the `bind9_version` fact|Templates use version-aware conditionals|Templates will use version-aware conditionals|tasks/main.yml \(planned implementation\)|read-only, set automatically|Users should not set this variable directly" docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml

Expected: no output.

  • Step 2: Confirm remaining runtime-detection mentions are future-only or negative-current statements

Run:

rg -n "runtime version detection|runtime detection|template conditionals|bind9_version" docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml

Expected: matches are acceptable only when they say runtime detection is not current behavior or is a possible future enhancement. There must be no match in meta/argument_specs.yml for bind9_version.

  • Step 3: Run lint if tools are available

Run:

if command -v yamllint >/dev/null 2>&1; then yamllint -d relaxed meta/argument_specs.yml; else echo 'yamllint not installed'; fi

Expected: either no lint errors, or the exact message:

yamllint not installed
  • Step 4: Review changed diff

Run:

git diff -- docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml

Expected: diff only changes wording/metadata for the branch-per-version strategy. No task files, templates, Molecule files, or runtime behavior files should be modified.

Task 6: Commit And Update Issue

Files:

  • Commit: docs/BIND9_9.20_SUPPORT.md

  • Commit: docs/VERSION_SUPPORT.md

  • Commit: meta/argument_specs.yml

  • Update: Gitea issue #15

  • Step 1: Commit the documentation and metadata fix

Run:

git add docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml
git commit -m "docs: clarify BIND9 9.20 branch strategy"

Expected: one commit is created with only the three scoped files.

  • Step 2: Push the branch

Run:

git push -u origin fix/issue-15-bind920-docs-strategy

Expected: branch is pushed to origin.

  • Step 3: Add implementation summary to issue #15

Use the Gitea MCP issue comment tool to add this summary after implementation:

Implemented the documentation and metadata correction for #15.

Changed:
- `docs/BIND9_9.20_SUPPORT.md`: current strategy is branch-per-version; runtime detection/template conditionals are future-only.
- `docs/VERSION_SUPPORT.md`: version-specific features now describe branch-level targeting and explicitly state runtime detection is not current behavior.
- `meta/argument_specs.yml`: removed the unsupported auto-detected `bind9_version` public option.

Validation:
- stale-claim search passed
- YAML syntax validation passed
- yamllint result: <record actual result>

Replace <record actual result> with either passed or not installed; syntax fallback passed.

Plan Self-Review

  • Spec coverage: all approved design requirements are covered by Tasks 2, 3, 4, and 5.
  • Placeholder scan: no implementation step depends on vague wording; the only value to replace is the final issue-comment lint result, which must be filled with actual command output at execution time.
  • Scope check: the plan changes only documentation and role metadata. It excludes runtime behavior, Molecule matrix work, and release tagging as required.
  • Type/path consistency: all paths match existing repository files and no new file paths are introduced.

Plan is ready for execution.

# Issue #15 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Make the BIND9 9.20 documentation and role argument metadata accurately describe the current branch-per-version strategy, without changing role behavior. **Architecture:** This is a documentation/metadata-only change. `docs/BIND9_9.20_SUPPORT.md` becomes the specific implementation guide for branch-based 9.20 support, `docs/VERSION_SUPPORT.md` keeps the broader version policy aligned with that strategy, and `meta/argument_specs.yml` stops advertising a `bind9_version` variable that the role does not set or consume. **Tech Stack:** Markdown, YAML, Ansible role metadata, local shell validation with `rg`, Python YAML parsing or `yamllint` if available. --- ## File Structure - Modify: `docs/BIND9_9.20_SUPPORT.md` - Responsibility: Explain the BIND9 9.20 support strategy and implementation status. Current behavior must be branch-per-version. Runtime detection must be future-only. - Modify: `docs/VERSION_SUPPORT.md` - Responsibility: Define the version support policy. It must not describe runtime detection as current or planned implementation for the active branch strategy. - Modify: `meta/argument_specs.yml` - Responsibility: Document the public role interface. It must not expose `bind9_version` as auto-detected behavior because no task sets it and no template uses it. No new files are required. --- ### Task 1: Prepare Branch And Capture Baseline **Files:** - Read: `docs/BIND9_9.20_SUPPORT.md` - Read: `docs/VERSION_SUPPORT.md` - Read: `meta/argument_specs.yml` - Read: `tasks/main.yml` - [ ] **Step 1: Create a ticket branch** Run: ```bash git switch -c fix/issue-15-bind920-docs-strategy ``` Expected: branch changes to `fix/issue-15-bind920-docs-strategy`. - [ ] **Step 2: Confirm only known untracked local files exist before editing** Run: ```bash git status --short ``` Expected: only pre-existing untracked local workspace files such as `.ansible/` and `.vscode/`, or a clean tree. Do not add those untracked local directories. - [ ] **Step 3: Capture stale runtime-detection claims** Run: ```bash rg -n "Runtime Version Detection|Template Conditionals|bind9_version|Version detection is automatic at runtime|tasks/main.yml \(planned implementation\)|Templates will use version-aware conditionals" docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml ``` Expected before editing: matches in all three files, including `docs/BIND9_9.20_SUPPORT.md`, `docs/VERSION_SUPPORT.md`, and `meta/argument_specs.yml`. --- ### Task 2: Correct `docs/BIND9_9.20_SUPPORT.md` **Files:** - Modify: `docs/BIND9_9.20_SUPPORT.md` - [ ] **Step 1: Replace the overview, architecture, branch, and implementation sections** Apply this patch: ```diff diff --git a/docs/BIND9_9.20_SUPPORT.md b/docs/BIND9_9.20_SUPPORT.md --- a/docs/BIND9_9.20_SUPPORT.md +++ b/docs/BIND9_9.20_SUPPORT.md @@ -This document describes the ansible-bind9-role implementation for BIND9 9.20+ support through the `feature/bind9-20-support` branch. +This document describes the ansible-bind9-role strategy for BIND9 9.20+ support through a dedicated version branch. + +The current implementation uses branch-level compatibility boundaries instead of runtime version detection. The `main` branch targets BIND9 9.18.x LTS, while the `9.20` branch targets BIND9 9.20+ feature releases. @@ -The role supports multiple BIND9 versions using: - -1. **Runtime Version Detection**: BIND9 version is detected at runtime and stored in the `bind9_version` fact -2. **Template Conditionals**: Jinja2 conditionals in templates apply version-specific configurations -3. **Separate Branches**: Different BIND9 feature release series are maintained on separate branches - - `main`: BIND9 9.18.x (LTS) - Production stable - - `9.20`: BIND9 9.20+ (feature releases) - New features and modern approach +The role supports multiple BIND9 versions with separate branches: + +1. **`main` branch**: BIND9 9.18.x LTS support for production-stable deployments. +2. **`9.20` branch**: BIND9 9.20+ feature-release support with version-specific templates, grammar data, tests, and documentation. + +The role does not currently detect BIND9 versions at runtime and does not use runtime version conditionals in templates. Each branch is expected to be tested against the BIND9 series it supports. + +This approach is preferred because: + +- compatibility boundaries are clear for users and maintainers; +- templates avoid cross-version conditional complexity; +- each branch can evolve with the grammar and package behavior of its target BIND9 series; +- generated configuration does not silently change based on the installed package version. @@ -main # BIND9 9.18.x LTS (stable) -│ -└─ 9.20 # BIND9 9.20+ feature releases - ├─ feature/bind9-20-support # Current development branch - └─ (will merge to 9.20 after testing) +main # BIND9 9.18.x LTS support +│ +└─ 9.20 # BIND9 9.20+ feature-release support + └─ feature/* # Short-lived feature branches targeting 9.20 ``` ## Implementation Details -### 1. Version Detection (tasks/main.yml) - -```yaml -- name: Detect BIND9 version at runtime - ansible.builtin.command: - cmd: named -v - register: _bind9_version_output - changed_when: false - -- name: Set bind9_version fact - ansible.builtin.set_fact: - bind9_version: "{{ _bind9_version_output.stdout | regex_search('BIND (\\S+)', '\\1') | first }}" -``` - -### 2. Meta/Argument Specs Updates - -The `meta/argument_specs.yml` has been updated to: - -- Document BIND9 9.20+ support alongside 9.18.x -- Add `bind9_version` variable documentation (read-only, auto-detected) -- Clarify version-specific behavior - -### 3. Molecule Testing +### 1. Current Role Task Flow + +The role currently follows the same task structure on each version branch: + +1. Install the configured BIND9 packages from `bind9_packages`. +2. Ensure backup and logging directories exist when enabled or configured. +3. Render configured BIND9 files through `named.conf.generator.j2`. +4. Validate the generated configuration with `named-checkconf -z`. +5. Restore backed-up configuration files if validation fails. +6. Start and enable the `named` service. + +There is no runtime `bind9_version` fact in this flow. + +### 2. Meta/Argument Specs + +The `meta/argument_specs.yml` file documents the public role inputs for the current branch. It must not document runtime-only variables that the role does not set or consume. + +### 3. Molecule Testing @@ -### 4. Template Version Compatibility +### 4. Template Version Compatibility @@ -Templates have been audited for BIND9 9.20 compatibility. The primary template files include: +Templates in each version branch should be audited for the BIND9 series targeted by that branch. The primary template files include: @@ -### 5. Deprecated Options Handling +### 5. Deprecated Options Handling @@ -BIND9 9.20 removes 44 options from 9.18. The role handles this through: +BIND9 9.20 removes 44 options from 9.18. The 9.20 branch should handle this through: 1. **Documentation**: Each deprecated option is documented in BIND9_MIGRATION_GUIDE.md -2. **Conditional Removal**: Templates check version and exclude removed options +2. **Branch-specific templates**: Templates on the 9.20 branch omit removed options 3. **Migration Path**: BIND9_MIGRATION_GUIDE.md provides alternatives for each removed option ``` - [ ] **Step 2: Reframe future enhancements** In `docs/BIND9_9.20_SUPPORT.md`, update the `## Future Enhancements` list so it includes runtime detection only as a future alternative. The resulting list must include these items exactly: ```markdown ## Future Enhancements - [ ] Automated configuration migration tool - [ ] Deprecation warnings in role output - [ ] Runtime version detection if branch-per-version maintenance becomes insufficient - [ ] Template conditionals only if a future design intentionally supports multiple BIND9 series from one branch - [ ] 9.21+ preparation when available - [ ] Performance tuning for 9.20 features - [ ] DNS-over-HTTPS (DoH) support - [ ] Clustering/high-availability examples ``` - [ ] **Step 3: Verify the document no longer presents runtime detection as current** Run: ```bash rg -n "Runtime Version Detection|Template Conditionals|bind9_version|detected at runtime|Conditional Removal|Templates check version" docs/BIND9_9.20_SUPPORT.md ``` Expected after editing: no matches except acceptable future-only wording for runtime detection/template conditionals. If a match implies current behavior, revise it before continuing. --- ### Task 3: Correct `docs/VERSION_SUPPORT.md` **Files:** - Modify: `docs/VERSION_SUPPORT.md` - [ ] **Step 1: Replace the version-specific features section** Replace the section from `## Version-Specific Features` through the end of the `### Conditional Configuration` subsection with this content: ```markdown ## Version-Specific Features ### Branch-Level Version Targeting The role currently uses branch-level version targeting instead of runtime version detection: - `main` targets BIND9 9.18.x LTS. - `9.20` targets BIND9 9.20+ feature releases. Each branch carries the templates, grammar data, documentation, and tests appropriate for its supported BIND9 series. This keeps generated configuration predictable and avoids mixing incompatible BIND9 grammar rules in one template path. ### Runtime Detection Runtime version detection is not part of the current implementation. The role does not set `bind9_version_full`, `bind9_version_major`, `bind9_version_minor`, or `bind9_version`, and templates do not branch on those values. Runtime detection may be reconsidered in the future if maintaining separate version branches becomes more expensive than supporting multiple BIND9 series from one branch. That future design would require dedicated tasks, public metadata, template changes, and Molecule coverage before being documented as supported behavior. ``` - [ ] **Step 2: Verify the policy no longer includes planned runtime-detection code examples** Run: ```bash rg -n "tasks/main.yml \(planned implementation\)|bind9_version_full|bind9_version_major|bind9_version_minor|Templates will use version-aware conditionals|templates/named.conf.options.j2 \(planned\)" docs/VERSION_SUPPORT.md ``` Expected after editing: no output. --- ### Task 4: Correct `meta/argument_specs.yml` **Files:** - Modify: `meta/argument_specs.yml` - [ ] **Step 1: Remove false runtime-detection wording from the role description** Change the `argument_specs.main.description` block from: ```yaml description: - Configures BIND9 DNS server on Debian-based systems. - "Supported BIND9 versions: 9.18.x (LTS), 9.20+ (feature releases)" - Version detection is automatic at runtime. ``` to: ```yaml description: - Configures BIND9 DNS server on Debian-based systems. - "Supported BIND9 versions are branch-specific: main targets 9.18.x (LTS), and the 9.20 branch targets 9.20+ feature releases." ``` - [ ] **Step 2: Remove the unsupported `bind9_version` option** Delete this option block entirely: ```yaml bind9_version: type: str description: - BIND9 version detected at runtime (read-only, set automatically). - "Format: X.Y.Z (e.g., 9.18.44, 9.20.18)" - Used by templates to apply version-specific configurations. - Users should not set this variable directly. ``` - [ ] **Step 3: Validate YAML syntax** Run: ```bash python3 - <<'PY' from pathlib import Path import yaml for path in [Path('meta/argument_specs.yml')]: yaml.safe_load(path.read_text()) print(f'OK {path}') PY ``` Expected: ```text OK meta/argument_specs.yml ``` If `PyYAML` is not installed, run this fallback: ```bash python3 - <<'PY' from pathlib import Path path = Path('meta/argument_specs.yml') text = path.read_text() assert 'bind9_version:' not in text assert 'Version detection is automatic at runtime.' not in text print(f'OK {path}') PY ``` Expected: ```text OK meta/argument_specs.yml ``` --- ### Task 5: Run Focused Validation **Files:** - Read: `docs/BIND9_9.20_SUPPORT.md` - Read: `docs/VERSION_SUPPORT.md` - Read: `meta/argument_specs.yml` - [ ] **Step 1: Search for stale current-behavior claims** Run: ```bash rg -n "Version detection is automatic at runtime|BIND9 version is detected at runtime|stored in the `bind9_version` fact|Templates use version-aware conditionals|Templates will use version-aware conditionals|tasks/main.yml \(planned implementation\)|read-only, set automatically|Users should not set this variable directly" docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml ``` Expected: no output. - [ ] **Step 2: Confirm remaining runtime-detection mentions are future-only or negative-current statements** Run: ```bash rg -n "runtime version detection|runtime detection|template conditionals|bind9_version" docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml ``` Expected: matches are acceptable only when they say runtime detection is not current behavior or is a possible future enhancement. There must be no match in `meta/argument_specs.yml` for `bind9_version`. - [ ] **Step 3: Run lint if tools are available** Run: ```bash if command -v yamllint >/dev/null 2>&1; then yamllint -d relaxed meta/argument_specs.yml; else echo 'yamllint not installed'; fi ``` Expected: either no lint errors, or the exact message: ```text yamllint not installed ``` - [ ] **Step 4: Review changed diff** Run: ```bash git diff -- docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml ``` Expected: diff only changes wording/metadata for the branch-per-version strategy. No task files, templates, Molecule files, or runtime behavior files should be modified. --- ### Task 6: Commit And Update Issue **Files:** - Commit: `docs/BIND9_9.20_SUPPORT.md` - Commit: `docs/VERSION_SUPPORT.md` - Commit: `meta/argument_specs.yml` - Update: Gitea issue `#15` - [ ] **Step 1: Commit the documentation and metadata fix** Run: ```bash git add docs/BIND9_9.20_SUPPORT.md docs/VERSION_SUPPORT.md meta/argument_specs.yml git commit -m "docs: clarify BIND9 9.20 branch strategy" ``` Expected: one commit is created with only the three scoped files. - [ ] **Step 2: Push the branch** Run: ```bash git push -u origin fix/issue-15-bind920-docs-strategy ``` Expected: branch is pushed to `origin`. - [ ] **Step 3: Add implementation summary to issue #15** Use the Gitea MCP issue comment tool to add this summary after implementation: ```markdown Implemented the documentation and metadata correction for #15. Changed: - `docs/BIND9_9.20_SUPPORT.md`: current strategy is branch-per-version; runtime detection/template conditionals are future-only. - `docs/VERSION_SUPPORT.md`: version-specific features now describe branch-level targeting and explicitly state runtime detection is not current behavior. - `meta/argument_specs.yml`: removed the unsupported auto-detected `bind9_version` public option. Validation: - stale-claim search passed - YAML syntax validation passed - yamllint result: <record actual result> ``` Replace `<record actual result>` with either `passed` or `not installed; syntax fallback passed`. --- ## Plan Self-Review - Spec coverage: all approved design requirements are covered by Tasks 2, 3, 4, and 5. - Placeholder scan: no implementation step depends on vague wording; the only value to replace is the final issue-comment lint result, which must be filled with actual command output at execution time. - Scope check: the plan changes only documentation and role metadata. It excludes runtime behavior, Molecule matrix work, and release tagging as required. - Type/path consistency: all paths match existing repository files and no new file paths are introduced. Plan is ready for execution.
daniel commented 2026-07-02 09:17:21 +00:00
Author
Owner
Copy Link
Copy Source

Implemented the documentation and metadata correction for #15.

Changed:

  • docs/BIND9_9.20_SUPPORT.md: current strategy is branch-per-version; runtime detection/template conditionals are future-only or negative-current.
  • docs/VERSION_SUPPORT.md: version-specific features now describe branch-level targeting and explicitly state runtime detection is not current behavior.
  • meta/argument_specs.yml: removed the unsupported auto-detected bind9_version public option.
  • docs/BIND9_MIGRATION_GUIDE.md: removed a test-playbook example variable that implied bind9_version was a supported role input.

Validation:

  • stale-claim search passed
  • remaining runtime-detection mentions are negative-current/future-only
  • YAML syntax validation passed
  • yamllint result: not installed; PyYAML syntax passed

PR: #20

Implemented the documentation and metadata correction for #15. Changed: - `docs/BIND9_9.20_SUPPORT.md`: current strategy is branch-per-version; runtime detection/template conditionals are future-only or negative-current. - `docs/VERSION_SUPPORT.md`: version-specific features now describe branch-level targeting and explicitly state runtime detection is not current behavior. - `meta/argument_specs.yml`: removed the unsupported auto-detected `bind9_version` public option. - `docs/BIND9_MIGRATION_GUIDE.md`: removed a test-playbook example variable that implied `bind9_version` was a supported role input. Validation: - stale-claim search passed - remaining runtime-detection mentions are negative-current/future-only - YAML syntax validation passed - yamllint result: not installed; PyYAML syntax passed PR: https://git.valid.dk/daniel/ansible-bind9-role/pulls/20
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
daniel (Daniel Akulenok)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: daniel/ansible-bind9-role#15
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?