daniel/ansible-bind9-role
1
0
Fork 0
Code Issues 3 Pull Requests 2 Actions Projects Releases Wiki Activity
Files
fix/issue-15-bind920-docs-strategy
ansible-bind9-role/docs/VERSION_SUPPORT.md
T
Daniel Akulenok 957efdf7c7
Test / Lint (pull_request) Failing after 1m3s
Details
Test / Test (pull_request) Has been skipped
Details
docs: clarify BIND9 9.20 branch strategy
2026-07-02 10:44:41 +02:00

11 KiB
Raw Permalink Blame History

BIND9 Version Support Policy

Document Version: 1.0
Last Updated: 2026-02-07
Role Version: Current development

Overview

This document defines the version maintenance strategy for the ansible-bind9-role, including supported BIND9 versions, OS platforms, branching strategy, and release management policies.

Supported Versions

BIND9 Versions

BIND9 Version Branch Status Support Level EOL Date
9.18.x (LTS) main ✅ Active Full support TBD (following ISC LTS timeline)
9.20.x+ 9.20 🚧 In Development Planned N/A

Version Selection Rationale

  • BIND9 9.18: Long Term Support (LTS) release from ISC

    • Maintained by ISC with extended support timeline
    • Stable feature set suitable for production environments
    • Current focus of this role

  • BIND9 9.20+: Feature release series

    • Introduces significant configuration changes
    • New features and modernization
    • May have shorter support windows per release
    • Will be supported in separate branch to prevent breaking changes

Operating System Support Matrix

OS Distribution Versions BIND9 9.18 BIND9 9.20+ Notes
Debian 11 (Bullseye) ✅ Supported 🔍 Testing Current stable
Debian 12 (Bookworm) ✅ Supported ✅ Supported Current testing focus
Debian 13 (Trixie) ✅ Supported ✅ Supported Future stable
Ubuntu 20.04 LTS ✅ Supported 🔍 Testing LTS until 2025
Ubuntu 22.04 LTS ✅ Supported ✅ Supported LTS until 2027
Ubuntu 24.04 LTS ✅ Supported ✅ Supported LTS until 2029

Legend:

  • ✅ Supported: Fully tested and supported
  • 🔍 Testing: In testing, use with caution
  • ⚠️ Limited: Basic support only
  • ❌ Unsupported: Not supported

Minimum Requirements

  • Ansible: 2.13 or later
  • Python: 3.8 or later (on controller and managed nodes)
  • BIND9 Packages: Must be available in distribution repositories or custom sources

Branching Strategy

Branch Structure

main                    # BIND9 9.18 LTS (stable)
├── 9.20                # BIND9 9.20+ development
├── docs                # Documentation updates (merged to both)
└── feature/*           # Feature branches (target appropriate base)

Branch Policies

main Branch

  • Purpose: Production-ready code for BIND9 9.18 LTS
  • Stability: Stable, tested releases only
  • Breaking Changes: Not allowed
  • Version Tagging: v1.x.x, v2.x.x, etc.

9.20 Branch

  • Purpose: Development for BIND9 9.20+ support
  • Stability: Development/testing phase
  • Breaking Changes: Allowed (vs 9.18 configurations)
  • Version Tagging: v9.20.x-betaX, v9.20.x-rcX, v9.20.x

Feature Branches

  • Naming: feature/description or fix/issue-number
  • Target: Merge to appropriate base (main for 9.18, 9.20 for 9.20+)
  • Lifecycle: Delete after merge

Backporting Policy

Security Fixes

  • Policy: MUST be backported to all supported branches
  • Timeline: Within 48 hours of fix
  • Priority: Critical

Bug Fixes

  • Policy: SHOULD be backported if:
    • Affects both versions
    • Low risk of introducing regressions
    • Reasonable effort required
  • Timeline: Within 1 week
  • Priority: High

New Features

  • Policy: Case-by-case evaluation
  • Criteria:
    • Feature is compatible with both BIND9 versions
    • Does not introduce breaking changes
    • Provides significant value
    • Low implementation complexity
  • Timeline: Best effort
  • Priority: Medium

Breaking Changes

  • Policy: NEVER backported
  • Implementation: Only in version-specific branches

Release Management

Version Numbering

Following Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH

MAJOR: Incompatible API changes (role variable structure changes)
MINOR: New functionality in a backwards compatible manner
PATCH: Backwards compatible bug fixes

Examples

  • v1.2.3: Patch release for BIND9 9.18
  • v2.0.0: Major release with breaking role variable changes
  • v9.20.0-beta1: Beta release for BIND9 9.20 support
  • v9.20.0: First stable release for BIND9 9.20

Release Cadence

  • Patch Releases: As needed for bug fixes and security updates
  • Minor Releases: Quarterly (or when significant features accumulate)
  • Major Releases: Annually (or when breaking changes are necessary)

Pre-release Testing

All releases must pass:

  1. Molecule tests across all supported platforms
  2. named-checkconf validation for all example configurations
  3. Manual testing on at least 2 different distributions
  4. Documentation review and update

Release Checklist

  • Update CHANGELOG.md with all changes
  • Update version in meta/main.yml
  • Run full molecule test suite
  • Update README.md if needed
  • Create annotated git tag
  • Push tag to trigger CI/CD
  • Create GitHub/Gitea release with notes
  • Announce on project channels

Testing Strategy

Test Matrix

Molecule Scenarios

Scenario Distribution BIND9 Version Purpose
default Debian 13 9.18 Primary development testing
ubuntu2204 Ubuntu 22.04 9.18 LTS testing
ubuntu2404 Ubuntu 24.04 9.18/9.20 Future-proofing
debian12 Debian 12 9.18 Stable release testing

Test Coverage

  • Syntax validation: All templates pass named-checkconf
  • Service management: Start, stop, reload, restart operations
  • Configuration types: All zone types and statement blocks
  • Edge cases: Empty configurations, complex nested structures
  • Upgrade scenarios: Migration from previous role versions

Continuous Integration

# .github/workflows/test.yml (example structure)
on: [push, pull_request]
jobs:
  molecule:
    strategy:
      matrix:
        distro: [debian12, debian13, ubuntu2204, ubuntu2404]
        bind_version: ['9.18', '9.20']
        exclude:
          # Don't test 9.20 on older distributions
          - distro: ubuntu2004
            bind_version: '9.20'

Grammar Tracking and Validation

Automated Grammar Comparison

The role maintains upstream BIND9 grammar files to:

  1. Detect configuration syntax changes between versions
  2. Identify deprecated and removed options
  3. Document breaking changes for users

Grammar Repository Structure

bind9-grammar/
├── upstream/
│   ├── v9.18.44/           # Latest 9.18 LTS grammar
│   │   ├── grammar/
│   │   │   ├── options
│   │   │   ├── *.zoneopt
│   │   │   └── parsegrammar.py
│   │   └── metadata.json
│   └── v9.20.18/           # Latest 9.20 grammar
│       ├── grammar/
│       └── metadata.json
├── 9.18/                   # Current 9.18 JSON schemas
│   └── *.json
└── 9.20/                   # Future 9.20 JSON schemas
    └── *.json

Validation Tools

scripts/fetch_bind_grammar.py

  • Fetches grammar files from Gitea mirror (Mirrors/bind9)
  • Supports version tags (e.g., v9.18.44, v9.20.18)
  • Stores upstream grammar for comparison

scripts/compare_bind_versions.py

  • Compares grammar files between versions
  • Generates docs/BIND_VERSION_DIFFERENCES.md
  • Identifies:
    • Breaking changes (removed options)
    • New features (added options)
    • Modified syntax
    • Deprecation notices

Grammar Update Workflow

  1. Monitor: Watch Gitea mirror for new BIND9 releases
  2. Fetch: Run fetch_bind_grammar.py for new version
  3. Compare: Run compare_bind_versions.py to identify changes
  4. Review: Analyze breaking changes and impact
  5. Update: Modify templates and variables as needed
  6. Test: Run molecule tests with new version
  7. Document: Update BIND_VERSION_DIFFERENCES.md and CHANGELOG.md

Deprecation Policy

Deprecation Process

  1. Announcement: Document deprecation in CHANGELOG.md and README.md
  2. Warning Period: Minimum 2 minor releases before removal
  3. Alternative: Provide migration path or alternative approach
  4. Removal: Only in major version releases

Current Deprecations

None at this time

Planned Deprecations

To be determined based on BIND9 9.20 analysis

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.

Migration Guidance

Migrating from BIND9 9.18 to 9.20

When BIND9 9.20 support is released:

  1. Review: Read docs/BIND_VERSION_DIFFERENCES.md
  2. Test: Use 9.20 branch in test environment
  3. Update: Modify playbook variables for deprecated/removed options
  4. Validate: Run named-checkconf against generated configuration
  5. Deploy: Upgrade BIND9 package and deploy new configuration
  6. Monitor: Check logs for warnings or errors

Migrating Between Role Versions

See CHANGELOG.md for version-specific migration notes.

Support and Contribution

Getting Help

  • Issues: Report bugs and request features on Gitea
  • Documentation: Refer to README.md and CONFIGURATION_GRAMMAR.md
  • Examples: Check tests/ directory for working configurations

Contributing

  • Bug Fixes: Target main branch (or 9.20 if version-specific)
  • Features: Discuss in issue before implementation
  • Testing: Ensure molecule tests pass
  • Documentation: Update relevant documentation files

Governance

  • Maintainer: Primary maintainer approves all merges
  • Review: All changes require review before merge
  • Testing: CI/CD must pass before merge

Future Considerations

BIND9 9.21+ and Beyond

  • Monitor ISC release announcements
  • Evaluate need for additional branches
  • Consider dropping support for EOL'd distributions
  • Reassess branching strategy if maintenance burden increases

Automation Improvements

  • Automated grammar fetching in CI
  • Automated breaking change detection
  • Version compatibility testing matrix
  • Documentation generation from grammar files

References

Changelog

Date Version Changes
2026-02-07 1.0 Initial version support policy
Reference in New Issue View Git Blame Copy Permalink