agama-yast-versioning.md

Analysis: Current vs. Proposed Versioning Approach

Current Approach: Multi-Part Versioning (5.0.X.Y)

How it works:

• YaST packages use semantic-like versioning: MAJOR.MINOR.PATCH.MAINTENANCE
• Example: 5.0.3.1 → version 5.0.3 with maintenance update 1
• The fourth number was recently added for maintenance releases

Critical limitation: The major and minor versions are completely frozen and meaningless.

• Major and minor will stay 5.0 forever - they never increment
• Only the third and fourth numbers change: 5.0.X.Y
• Not following semantic versioning: API changes are introduced without incrementing the major version
• The format creates false expectations: It looks like SemVer but doesn't follow SemVer rules

Real-world example of the problem:

5.0.1     - Initial release
5.0.2     - Bug fixes
5.0.3     - New feature added
5.0.4     - BREAKING API CHANGE (but major version stays at 5!)
5.0.4.1   - Maintenance update
5.0.5     - Another feature
5.0.6     - ANOTHER BREAKING CHANGE (major still 5.0!)

The 5.0 prefix never changes, even when breaking changes occur, making the versioning misleading for anyone who expects semantic versioning behavior.

Pros:

1. Familiar pattern: Resembles semantic versioning (SemVer), which is widely understood
2. Tooling compatibility: Most package managers handle multi-part versions well

Cons:

1. Frozen meaningless segments: Major and minor (5.0) are permanently fixed and convey zero information
2. Violates expectations: Looks like SemVer but breaks API compatibility without version changes
3. Misleading format: The MAJOR.MINOR prefix falsely implies semantic meaning
4. Version inflation: Four numbers when only two matter (5.0.3.1 vs. simpler alternatives)
5. Cognitive overhead: Developers must remember that only positions 3 and 4 matter
6. Inconsistency with Agama: Agama uses single-number versioning, creating divergent patterns
7. Maintenance complexity: Four-part versions are harder to parse and compare
8. Wasted positions: Two of four version positions carry no information

Proposed Approach: Single-Number Versioning (6.X)

How it works:

• YaST packages for Agama use versions >= 6
• Base version increments with each development cycle
• Maintenance updates add a decimal: 6.1, 6.2, etc.
• Aligns with Agama's versioning scheme

Pros:

1. Simplicity: Single number is easier to understand and communicate
2. Meaningful versioning: Every number increment represents actual change
3. Consistency: Matches Agama's versioning pattern (24, 38, etc.)
4. Clear Agama differentiation: Versions >= 6 immediately signal "Agama-maintained"
5. Reduced confusion: No false semantic versioning expectations
6. Easier maintenance tracking: 6.1 → 6.2 is simpler than 5.0.3.1 → 5.0.3.2
7. Lower cognitive load: Fewer numbers to track and remember

Cons:

1. Breaking from convention: Deviates from common package versioning patterns
2. Limited granularity: Can't easily distinguish between feature/bugfix/breaking changes
3. Potential tooling friction: Some tools expect multi-part versions
4. Version collision risk: Must ensure version 6+ is reserved for Agama use
5. Migration effort: Switching from 5.0.X.Y to 6 requires process changes
6. Less information density: Can't encode multiple change dimensions in version number

Visual Comparison: Meaningful vs. Meaningless Positions

Current approach (5.0.X.Y):

5  .  0  .  3  .  1
↑     ↑     ↑     ↑
│     │     │     └─ Maintenance update (MEANINGFUL)
│     │     └─────── Patch version (MEANINGFUL)
│     └─────────────── Forever frozen at 0 (MEANINGLESS)
└───────────────────── Forever frozen at 5 (MEANINGLESS)

Result: 50% of version positions carry zero information

Proposed approach (6.X):

6  .  1
↑     ↑
│     └─ Maintenance update (MEANINGFUL)
└─────── Base version / Agama fork indicator (MEANINGFUL)

Result: 100% of version positions carry information

Comparative Analysis

Aspect	Current (5.0.X.Y)	Proposed (6.X)
Simplicity	★★☆☆☆	★★★★★
Meaningful information	★★☆☆☆ (50% wasted)	★★★★★ (100% meaningful)
Consistency with Agama	★☆☆☆☆	★★★★★
Semantic versioning compliance	★☆☆☆☆ (looks like SemVer, isn't)	★★★★☆ (honest non-SemVer)
Familiarity	★★★★☆	★★☆☆☆
Maintenance clarity	★★☆☆☆	★★★★☆
Tooling compatibility	★★★★★	★★★★☆

Recommendation

The proposed single-number versioning (6.X) is strongly recommended for YaST packages maintained for Agama for the following reasons:

1. Eliminates meaningless positions: Current 5.0.X.Y wastes two positions that never change - the proposed scheme uses only meaningful numbers
2. Honesty over pretense: Doesn't masquerade as semantic versioning while violating its principles (API changes without major version bumps)
3. Alignment: Creates a unified versioning philosophy across the Agama ecosystem
4. Simplicity: Two numbers that both matter (6.1) vs. four numbers where only two matter (5.0.3.1)
5. Clarity: Version 6+ immediately signals "this is the Agama fork"
6. Pragmatism: In the Agama context, the primary concern is tracking development cycles and maintenance updates, which the simpler scheme handles well

The current approach's fundamental flaw is that it uses a four-part version number where half the positions are permanently frozen at 5.0, creating visual noise and false expectations about semantic versioning compliance. The proposed scheme directly addresses this by using only the numbers that actually change.

Implementation Considerations

If adopting the proposed approach:

1. Documentation: Clearly document the versioning scheme and rationale
2. Branch naming: Ensure maintenance branches follow consistent patterns (yast-storage-ng/SLE-16.0)
3. Version reservation: Document that versions < 6 are traditional YaST, >= 6 are Agama-maintained
4. Tooling: Verify that RPM, OBS, and other build tools handle the simpler versioning
5. Communication: Announce the change to avoid confusion among maintainers and users
6. Changelog: Maintain clear changelogs since version numbers provide less semantic information