### What needs to get done ## Executive Summary We propose introducing a metadata separation in Snapcraft that distinguishes between "workload version" and "snap version" to improve user experience and version transparency. This change would help users better understand what software versions are actually installed on their systems. ## Problem Statement Currently, snap versions displayed by `snap list` combine the upstream application version with snap-specific packaging information in a single field. This creates several issues: 1. **Inconsistent version formats**: Different developers use varying approaches to version formatting, making it difficult for users to identify the actual application version 2. **Unclear versioning**: Users cannot easily distinguish between the upstream software version and the snap packaging version 3. **Comparison difficulties**: It's challenging to compare installed versions with upstream releases or other packaging formats ### Why Snap Revision Numbers Are Insufficient While snap revisions (the "Rev" column) provide build ordering, they fail to address user needs for several critical reasons: 1. **Version-agnostic revisions**: Multiple revisions can contain identical workload versions. For example, revisions 100, 101, and 102 might all contain the same upstream software version (e.g., Firefox 120.0) but differ only in: - Metadata updates - Hook script modifications - Configuration changes - Security patches to the snap infrastructure - Build environment updates 2. **No semantic meaning**: Revision numbers are sequential integers that provide no information about the nature or significance of changes. Users cannot determine whether a `snap refresh` will: - Update the actual application to a newer version - Apply only packaging/infrastructure changes - Fix security issues in the snap itself (not the workload) 3. **False update expectations**: When users see a higher revision number available, they might expect new application features or bug fixes, when in reality only snap metadata or hooks have changed. 4. **Inability to track workload stability**: System administrators cannot easily identify which snaps have stable workload versions across multiple revisions, making it difficult to: - Plan maintenance windows appropriately - Assess the impact of updates on end-users - Determine when application testing is required vs. when only snap infrastructure has changed 5. **Cross-channel comparison issues**: The same workload version might have different revision numbers across channels (stable, candidate, beta), making it impossible to determine version equivalence without additional investigation. ### Current Version Format Examples From the current `snap list` output, we see various inconsistent formats: - `128.13.0esr-3` (Thunderbird) - ESR version with snap revision - `3.0.20-1-g2617de71b6` (VLC) - Version with git commit info - `v4.16.3.20eef26` (Whatsie) - Version with additional identifiers - `2021.12.17+git01bf89e` (youtube-dl) - Date-based with git reference ## Proposed Solution ### Metadata Schema Changes Introduce two distinct version fields in snap metadata: 1. **Workload Version**: The upstream application's native version (e.g., `128.13.0esr`, `3.0.20`, `4.16.3`) 2. **Snap Version**: The snap-specific packaging version/revision (e.g., `3`, `1`, `20eef26`) ### Implementation Approach 1. **Backward Compatibility**: Maintain the current `version` field while adding new `workload-version` and `snap-version` fields 2. **Migration Path**: Allow developers to gradually adopt the new format 3. **Display Options**: Provide command-line flags to show different version views ## Example Output Comparison ### Current Format ``` Name Version Rev Tracking Publisher Notes thunderbird 128.13.0esr-3 769 latest/stable canonical✓ - vlc 3.0.20-1-g2617de71b6 3777 latest/stable videolan✓ - whatsie v4.16.3.20eef26 165 latest/stable keshavnrj✪ - wsstat v1.1.1-ba8c1bb 16 latest/stable jersson - youtube-dl 2021.12.17+git01bf89e 4806 latest/stable joeborg - yq v4.46.1 2726 latest/stable mikefarah - ``` ### Proposed Enhanced Format ``` Name Workload Ver Snap Ver Rev Tracking Publisher Notes thunderbird 128.13.0esr 3 769 latest/stable canonical✓ - vlc 3.0.20 1-g2617de71b6 3777 latest/stable videolan✓ - whatsie 4.16.3 20eef26 165 latest/stable keshavnrj✪ - wsstat 1.1.1 ba8c1bb 16 latest/stable jersson - youtube-dl 2021.12.17 git01bf89e 4806 latest/stable joeborg - yq 4.46.1 - 2726 latest/stable mikefarah - ``` ## Benefits 1. **Clarity**: Users can immediately identify the upstream application version 2. **Consistency**: Standardized display format across all snaps 3. **Compatibility**: Easy comparison with other package managers and upstream releases 4. **Flexibility**: Snap publishers can use appropriate versioning for their packaging needs 5. **Tooling**: Third-party tools can better parse and understand version information ## Implementation Considerations ### For Snap Publishers - **Optional Migration**: Publishers can adopt the new format gradually - **Validation**: Snapcraft could provide validation tools for version format compliance - **Documentation**: Clear guidelines on how to separate workload and snap versions ### For Users - **Command Options**: - `snap list --format=legacy` (current format) - `snap list --format=separated` (new format) - `snap list --workload-version-only` (show only upstream versions) ### For Snapcraft Core - **API Changes**: Extend the snap metadata API to include separate version fields - **Storage**: Update snap metadata storage to accommodate new fields - **Display Logic**: Implement flexible display formatting ## Migration Strategy 1. **Phase 1**: Introduce optional workload-version and snap-version fields 2. **Phase 2**: Update snapcraft tools to parse and validate separated versions 3. **Phase 3**: Encourage publisher adoption through documentation and tooling 4. **Phase 4**: Consider making separated versioning the default for new snaps ## Conclusion This metadata separation would significantly improve the snap ecosystem's usability and transparency. By clearly distinguishing between upstream software versions and snap packaging versions, users gain better insight into their installed software while maintaining full backward compatibility. The proposed change addresses a fundamental user experience issue that affects daily snap usage and would align Snapcraft with other modern package management systems that provide clear version separation. ### Why it needs to get done I have opened up a link in the forum about this proposal: https://forum.snapcraft.io/t/proposal-metadata-separation-of-snap-versions/48119