Improve Debian package changelog to show incremental version history #22

New issue

Closed

opened 2025-08-24 23:25:32 +02:00 by olemd · 0 comments

olemd commented

2025-08-24 23:25:32 +02:00

Owner

Problem

The Debian package changelog currently only shows changes since the most recent release, making it difficult for users to understand the complete history of changes when reviewing package updates. This creates a poor user experience and reduces transparency about the software's evolution.

Current Behavior

The scripts/build-deb.sh script generates a changelog that only includes changes since the previous tag:

Current Logic (lines 77-92):

# Get the current version and previous version  
CURRENT_VERSION=$(git describe --tags --always)
PREV_VERSION=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")

# Only shows changes since PREV_VERSION
git log --pretty=format:"  * %s" "$PREV_VERSION..HEAD" | head -20

Result: Each package only shows the most recent changes, losing historical context.

Example Current Changelog:

skyview (v0.0.3-3-g60ba5ae) unstable; urgency=medium

  Changes since v0.0.3:
  * Merge pull request 'Fix CPR zone ambiguity causing systematic eastward position bias' (#20) from fix/cpr-zone-ambiguity into main
  * Fix CPR zone ambiguity causing systematic eastward position bias
  * Add DEBIAN/conffiles to protect configuration files during upgrades
 -- Ole-Morten Duesund <olemd@glemt.net>  Sun, 24 Aug 2025 23:14:01 +0200

Expected Behavior

The changelog should be incremental, showing the complete version history in standard Debian changelog format:

Example Expected Changelog:

skyview (0.0.4) unstable; urgency=medium

  * Fix CPR zone ambiguity causing systematic eastward position bias  
  * Add comprehensive algorithm documentation with authoritative references
  * Eliminate tens-of-kilometers positioning errors for aircraft tracking

 -- Ole-Morten Duesund <olemd@glemt.net>  Sun, 24 Aug 2025 23:15:00 +0200

skyview (0.0.3) unstable; urgency=medium

  * Add active WebSocket client tracking and display
  * Add automatic changelog generation to Debian package build
  * Remove arbitrary 600kt speed cap from Mode S decoder

 -- Ole-Morten Duesund <olemd@glemt.net>  Wed, 15 Jan 2025 10:30:00 +0200

skyview (0.0.2) unstable; urgency=medium

  * Initial multi-source ADS-B aircraft tracker release
  * Beast binary format parsing with real-time WebSocket updates
  * Interactive maps with signal strength visualization

 -- Ole-Morten Duesund <olemd@glemt.net>  Mon, 06 Jan 2025 14:20:00 +0100

Benefits of Incremental Changelog

For Users:

Complete history visibility: See all changes when reviewing package updates
Better upgrade decisions: Understand cumulative improvements since their installed version
Security awareness: Track security fixes across multiple versions
Feature discovery: Learn about features added in versions they may have skipped

For Administrators:

Audit trail: Complete change history for compliance and troubleshooting
Rollback planning: Better understanding of what changed between specific versions
Documentation: Built-in release notes accessible via dpkg --info or apt changelog

For Distribution:

Standards compliance: Follows Debian Policy Manual guidelines for changelog format
Package manager integration: Works properly with apt changelog and similar tools
Archive quality: Better integration with Debian/Ubuntu package repositories

Implementation Options

Option 1: Iterative Changelog Generation (Recommended)

Generate changelog entries for all releases, with most recent at the top:

# Generate incremental changelog
generate_incremental_changelog() {
    local changelog_file="$1"
    
    # Get all tags in reverse chronological order  
    local tags=$(git tag -l --sort=-version:refname)
    local prev_tag=""
    
    # Create empty changelog
    > "$changelog_file"
    
    for tag in $tags; do
        local tag_date=$(git log -1 --format=%aD "$tag")
        local tag_commit=$(git rev-list -n 1 "$tag")
        
        # Add version header
        echo "skyview ($tag) unstable; urgency=medium" >> "$changelog_file"
        echo "" >> "$changelog_file"
        
        # Add changes for this version
        if [ -n "$prev_tag" ]; then
            git log --pretty=format:"  * %s" "$tag..$prev_tag" >> "$changelog_file"
        else
            # First release - use all commits up to this tag
            git log --pretty=format:"  * %s" "$tag" >> "$changelog_file"  
        fi
        
        echo "" >> "$changelog_file"
        echo " -- $(git config user.name) <$(git config user.email)>  $tag_date" >> "$changelog_file"
        echo "" >> "$changelog_file"
        
        prev_tag="$tag"
    done
}

Option 2: Persistent Changelog File

Maintain a debian/changelog file in the repository that gets updated with each release.

Option 3: Hybrid Approach

Combine automated generation with manual curation for important releases.

Impact

Current Impact:

Users see incomplete change history
Difficult to understand package evolution
Poor integration with standard Debian tools
Reduced transparency and trust

After Fix:

Complete version history in every package
Standard Debian changelog format compliance
Better user experience during upgrades
Proper integration with apt changelog skyview

Environment

Component: scripts/build-deb.sh changelog generation (lines 72-106)
File: debian/usr/share/doc/skyview/changelog.gz
Format: Debian changelog format per Debian Policy Manual
Tools: Git tags, dpkg-deb, gzip

References

Priority

Medium - Improves user experience and standards compliance, but doesn't affect functionality.

## Problem The Debian package changelog currently only shows changes since the most recent release, making it difficult for users to understand the complete history of changes when reviewing package updates. This creates a poor user experience and reduces transparency about the software's evolution. ## Current Behavior The `scripts/build-deb.sh` script generates a changelog that only includes changes since the previous tag: **Current Logic (lines 77-92):** ```bash # Get the current version and previous version CURRENT_VERSION=$(git describe --tags --always) PREV_VERSION=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "") # Only shows changes since PREV_VERSION git log --pretty=format:" * %s" "$PREV_VERSION..HEAD" | head -20 ``` **Result:** Each package only shows the most recent changes, losing historical context. ### Example Current Changelog: ``` skyview (v0.0.3-3-g60ba5ae) unstable; urgency=medium Changes since v0.0.3: * Merge pull request 'Fix CPR zone ambiguity causing systematic eastward position bias' (#20) from fix/cpr-zone-ambiguity into main * Fix CPR zone ambiguity causing systematic eastward position bias * Add DEBIAN/conffiles to protect configuration files during upgrades -- Ole-Morten Duesund <olemd@glemt.net> Sun, 24 Aug 2025 23:14:01 +0200 ``` ## Expected Behavior The changelog should be **incremental**, showing the complete version history in standard Debian changelog format: ### Example Expected Changelog: ``` skyview (0.0.4) unstable; urgency=medium * Fix CPR zone ambiguity causing systematic eastward position bias * Add comprehensive algorithm documentation with authoritative references * Eliminate tens-of-kilometers positioning errors for aircraft tracking -- Ole-Morten Duesund <olemd@glemt.net> Sun, 24 Aug 2025 23:15:00 +0200 skyview (0.0.3) unstable; urgency=medium * Add active WebSocket client tracking and display * Add automatic changelog generation to Debian package build * Remove arbitrary 600kt speed cap from Mode S decoder -- Ole-Morten Duesund <olemd@glemt.net> Wed, 15 Jan 2025 10:30:00 +0200 skyview (0.0.2) unstable; urgency=medium * Initial multi-source ADS-B aircraft tracker release * Beast binary format parsing with real-time WebSocket updates * Interactive maps with signal strength visualization -- Ole-Morten Duesund <olemd@glemt.net> Mon, 06 Jan 2025 14:20:00 +0100 ``` ## Benefits of Incremental Changelog ### For Users: - **Complete history visibility**: See all changes when reviewing package updates - **Better upgrade decisions**: Understand cumulative improvements since their installed version - **Security awareness**: Track security fixes across multiple versions - **Feature discovery**: Learn about features added in versions they may have skipped ### For Administrators: - **Audit trail**: Complete change history for compliance and troubleshooting - **Rollback planning**: Better understanding of what changed between specific versions - **Documentation**: Built-in release notes accessible via `dpkg --info` or `apt changelog` ### For Distribution: - **Standards compliance**: Follows Debian Policy Manual guidelines for changelog format - **Package manager integration**: Works properly with `apt changelog` and similar tools - **Archive quality**: Better integration with Debian/Ubuntu package repositories ## Implementation Options ### Option 1: Iterative Changelog Generation (Recommended) Generate changelog entries for all releases, with most recent at the top: ```bash # Generate incremental changelog generate_incremental_changelog() { local changelog_file="$1" # Get all tags in reverse chronological order local tags=$(git tag -l --sort=-version:refname) local prev_tag="" # Create empty changelog > "$changelog_file" for tag in $tags; do local tag_date=$(git log -1 --format=%aD "$tag") local tag_commit=$(git rev-list -n 1 "$tag") # Add version header echo "skyview ($tag) unstable; urgency=medium" >> "$changelog_file" echo "" >> "$changelog_file" # Add changes for this version if [ -n "$prev_tag" ]; then git log --pretty=format:" * %s" "$tag..$prev_tag" >> "$changelog_file" else # First release - use all commits up to this tag git log --pretty=format:" * %s" "$tag" >> "$changelog_file" fi echo "" >> "$changelog_file" echo " -- $(git config user.name) <$(git config user.email)> $tag_date" >> "$changelog_file" echo "" >> "$changelog_file" prev_tag="$tag" done } ``` ### Option 2: Persistent Changelog File Maintain a `debian/changelog` file in the repository that gets updated with each release. ### Option 3: Hybrid Approach Combine automated generation with manual curation for important releases. ## Impact **Current Impact:** - Users see incomplete change history - Difficult to understand package evolution - Poor integration with standard Debian tools - Reduced transparency and trust **After Fix:** - Complete version history in every package - Standard Debian changelog format compliance - Better user experience during upgrades - Proper integration with `apt changelog skyview` ## Environment - **Component**: `scripts/build-deb.sh` changelog generation (lines 72-106) - **File**: `debian/usr/share/doc/skyview/changelog.gz` - **Format**: Debian changelog format per Debian Policy Manual - **Tools**: Git tags, dpkg-deb, gzip ## References - [Debian Policy Manual - Source package control files -- debian/changelog](https://www.debian.org/doc/debian-policy/ch-source.html#debian-changelog-debian-changelog) - [Debian Developer's Reference - Best practices for debian/changelog](https://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html#bpp-debian-changelog) ## Priority **Medium** - Improves user experience and standards compliance, but doesn't affect functionality.