docs: Add version support policy and changelog

- Establish formal version maintenance strategy - Define BIND9 9.18 (LTS) and 9.20+ support tiers - Document branching strategy (main for 9.18, 9.20 for next major) - Define backporting policies for security, bugs, features - Create release management and CI/CD framework - Add OS platform compatibility matrix
2026-02-07 22:52:20 +01:00
parent 0271be7752
commit ef45f4ef0b
2 changed files with 484 additions and 0 deletions
--- a/docs/VERSION_SUPPORT.md
+++ b/docs/VERSION_SUPPORT.md
@@ -0,0 +1,370 @@
+# 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 |
+