diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3c6a784 --- /dev/null +++ b/CHANGELOG.md @@ -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) + diff --git a/docs/VERSION_SUPPORT.md b/docs/VERSION_SUPPORT.md new file mode 100644 index 0000000..6009f61 --- /dev/null +++ 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 | +