daniel/ansible-bind9-role
1
0
Fork 0
Code Issues 3 Pull Requests 2 Actions Projects Releases Wiki Activity
Files
957efdf7c7c1113ddefb371c9a0019026685d0b5
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

354 lines
11 KiB
Markdown
Raw 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](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
### 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
- [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 |
Reference in New Issue View Git Blame Copy Permalink