Proposal: Metadata Separation of Snap Versions

snapd
1

Proposal: Metadata Separation of Snap Versions

Executive Summary

We (Dwellir) 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.

3 Likes