60 lines
1.9 KiB
Markdown
60 lines
1.9 KiB
Markdown
# ADR-006: Package Versioning Strategy
|
|
|
|
**Date**: 2026-05-15
|
|
**Status**: Decided
|
|
**Deciders**: Kevin Adams
|
|
|
|
## Context
|
|
|
|
The package has historically had version strings tied to specific Proxmox or TrueNAS releases (e.g., `ZFSPlugin-8.0.5_1.pm.patch`, `pvemanagerlib-7.4-3_1.js.patch`). This creates confusion — users aren't sure if `2.2.0-1` means it works with TrueNAS 2.2 or Proxmox 2.2.
|
|
|
|
## Decision
|
|
|
|
The package version is **independent** of both Proxmox VE and TrueNAS versions.
|
|
|
|
- Package version: semantic versioning `MAJOR.MINOR.PATCH` (e.g., `3.0.0`, `3.1.2`)
|
|
- Supported Proxmox VE versions and TrueNAS versions are documented in:
|
|
- GitHub Release notes (the primary place — visible when users click on a release)
|
|
- The `Description` field in `DEBIAN/control`
|
|
- README.md compatibility table
|
|
|
|
## Version Scheme
|
|
|
|
| Series | Meaning |
|
|
|--------|---------|
|
|
| `2.x.x` | Current approach (ZFSPlugin.pm patch wedge) |
|
|
| `3.x.x` | New `TrueNASPlugin` custom storage type |
|
|
| `3.0.x` | Patch releases for 3.0 (bug fixes, no new features) |
|
|
| `3.1.x` | Next minor — could add features like snapshot support |
|
|
|
|
## GitHub Release Notes Template
|
|
|
|
Each release on GitHub should include:
|
|
|
|
```markdown
|
|
## freenas-proxmox v3.0.0
|
|
|
|
### Supported Proxmox VE Versions
|
|
- Proxmox VE 8.0, 8.1, 8.2, 8.3
|
|
|
|
### Supported TrueNAS Versions
|
|
- TrueNAS CORE 13.0-U6+
|
|
- TrueNAS SCALE 23.10+, 24.04+
|
|
|
|
### What's New
|
|
- ...
|
|
|
|
### Breaking Changes from v2.x
|
|
- Storage type changes from `ZFS over iSCSI (freenas provider)` to `TrueNAS (API)`
|
|
- Migration guide: [link]
|
|
```
|
|
|
|
## CI Version Injection
|
|
|
|
The version is set in one place: a `VERSION` file or git tag at the repo root. CI reads it and injects via `envsubst` into `packaging/DEBIAN/control.j2`.
|
|
|
|
Branch-to-channel mapping (not version mapping):
|
|
- `feature_*` → alpha channel
|
|
- `master` → beta/testing channel
|
|
- Tagged release (`v3.0.0`) → stable channel
|