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](https://semver.org/):

```
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

```yaml
# .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:

```yaml
# 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:

```jinja2
{# 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](https://bind9.readthedocs.io/)
- [ISC BIND9 Release Schedule](https://www.isc.org/bind/)
- [Semantic Versioning](https://semver.org/)
- [Ansible Best Practices](https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html)

## Changelog

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