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
This commit is contained in:
Daniel Akulenok
114
CHANGELOG.md
Normal file
114
CHANGELOG.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to the ansible-bind9-role will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- Version support policy documentation in `docs/VERSION_SUPPORT.md`
|
||||
- Branching strategy for supporting multiple BIND9 versions
|
||||
- Grammar comparison tooling (`scripts/compare_bind_versions.py`)
|
||||
- Grammar fetcher for upstream BIND9 sources (`scripts/fetch_bind_grammar.py`)
|
||||
- Automated version difference tracking
|
||||
- Operating system support matrix
|
||||
|
||||
### Changed
|
||||
- Established formal release management process
|
||||
- Defined backporting policy for security, bugs, and features
|
||||
|
||||
### Planned
|
||||
- BIND9 9.20+ support in separate `9.20` branch
|
||||
- Multi-platform molecule test matrix
|
||||
- Automated BIND9 version detection in tasks
|
||||
- Version-specific template conditional logic
|
||||
- Enhanced CI/CD pipeline with version matrix testing
|
||||
|
||||
## [1.0.0] - TBD
|
||||
|
||||
### Initial Release
|
||||
- Full support for BIND9 9.18.x (LTS)
|
||||
- Configuration grammar based on BIND9 9.18.44
|
||||
- Comprehensive template system for all BIND9 statement types:
|
||||
- `acl`
|
||||
- `controls`
|
||||
- `dlz`
|
||||
- `dnssec-policy`
|
||||
- `dyndb`
|
||||
- `http`
|
||||
- `key`
|
||||
- `logging`
|
||||
- `options`
|
||||
- `parental-agents`
|
||||
- `primaries` (masters)
|
||||
- `server`
|
||||
- `statistics-channels`
|
||||
- `tls`
|
||||
- `trust-anchors`
|
||||
- `view`
|
||||
- `zone` (all types: primary, secondary, forward, hint, stub, static-stub, mirror, redirect, in-view, delegation-only)
|
||||
- Support for Debian 11, 12, 13
|
||||
- Support for Ubuntu 20.04, 22.04, 24.04
|
||||
- Molecule testing framework
|
||||
- Configuration validation with `named-checkconf`
|
||||
- Automatic configuration backup and rollback on errors
|
||||
- Detailed configuration grammar documentation
|
||||
- GPL-3.0-or-later license
|
||||
|
||||
---
|
||||
|
||||
## Version History (Pre-Changelog)
|
||||
|
||||
Prior to this changelog, the role was developed without formal version tracking.
|
||||
This changelog starts with the establishment of the version support policy.
|
||||
|
||||
---
|
||||
|
||||
## Versioning Schema
|
||||
|
||||
- **MAJOR**: Incompatible changes to role variables or behavior
|
||||
- **MINOR**: New features in a backwards compatible manner
|
||||
- **PATCH**: Backwards compatible bug fixes
|
||||
|
||||
### Branch-Specific Versioning
|
||||
|
||||
- `main` branch: `vX.Y.Z` (BIND9 9.18 LTS)
|
||||
- `9.20` branch: `v9.20.X[-suffix]` (BIND9 9.20+)
|
||||
- Suffixes: `-alpha`, `-beta`, `-rc` for pre-releases
|
||||
|
||||
## Release Types
|
||||
|
||||
### Security Releases
|
||||
Critical security fixes are released as patch versions and backported to all supported branches.
|
||||
|
||||
### Feature Releases
|
||||
New features are added in minor version increments. Breaking changes require major version increments.
|
||||
|
||||
### Bug Fix Releases
|
||||
Bug fixes are released as patch versions when they accumulate or for critical issues.
|
||||
|
||||
## Upgrade Notes
|
||||
|
||||
### From Pre-Versioned to v1.0.0
|
||||
The first official release establishes baseline compatibility. Users of pre-release versions should:
|
||||
1. Review all role variables for any changes
|
||||
2. Test in non-production environment
|
||||
3. Review generated configuration with `named-checkconf`
|
||||
4. Check `docs/VERSION_SUPPORT.md` for supported platforms
|
||||
|
||||
### Future Upgrades
|
||||
Check individual version sections above for specific upgrade notes and breaking changes.
|
||||
|
||||
## Contributing
|
||||
|
||||
See `docs/VERSION_SUPPORT.md` for contribution guidelines and release processes.
|
||||
|
||||
## Links
|
||||
|
||||
- [Version Support Policy](docs/VERSION_SUPPORT.md)
|
||||
- [Configuration Grammar](CONFIGURATION_GRAMMAR.md)
|
||||
- [Issue Tracker](https://git.valid.dk/daniel/ansible-bind9-role/issues)
|
||||
- [Repository](https://git.valid.dk/daniel/ansible-bind9-role)
|
||||
|
||||
370
docs/VERSION_SUPPORT.md
Normal file
370
docs/VERSION_SUPPORT.md
Normal file
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user