ansible-bind9-role/docs/VERSION_SUPPORT.md

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

Version Detection

The role will detect BIND9 version at runtime:

# tasks/main.yml (planned implementation)
- name: Detect BIND9 version
  ansible.builtin.command: named -V
  register: _bind9_version_output
  changed_when: false

- name: Set BIND9 version facts
  ansible.builtin.set_fact:
    bind9_version_full: "{{ _bind9_version_output.stdout | regex_search('BIND (\\S+)', '\\1') | first }}"
    bind9_version_major: "{{ _bind9_version_output.stdout | regex_search('BIND (\\d+)\\.(\\d+)', '\\1') | first }}"
    bind9_version_minor: "{{ _bind9_version_output.stdout | regex_search('BIND (\\d+)\\.(\\d+)', '\\2') | first }}"

Conditional Configuration

Templates will use version-aware conditionals:

{# templates/named.conf.options.j2 (planned) #}
{% if bind9_version_major | int >= 20 %}
    {# BIND9 9.20+ specific options #}
{% else %}
    {# BIND9 9.18 options #}
{% endif %}

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

• ISC BIND9 Documentation
• ISC BIND9 Release Schedule
• Semantic Versioning
• Ansible Best Practices

Changelog

Date	Version	Changes
2026-02-07	1.0	Initial version support policy