Bug 165115 – Current portage changelog referring to tracker bug is inadequate documentation

• Product: Portage Development
• Status: RESOLVED FIXED

[Description Wilbur Pan 2007-02-03 12:09:37 UTC]

I've noticed that the changelogs for the past few portage releases point to tracker bugs.  The problem is that the current tracker bug for portage-2.1.2-r6 tracks all bugs going back to 2.1.2-r1, making it difficult to see which exactly which bugs were fixed if you are upgrading from, say, 2.1.2-r5 to 2.1.2-r6.

Reproducible: Always

Steps to Reproduce:
Look at the portage changelog.

Actual Results:  
I see this:

*portage-2.1.2-r6 (02 Feb 2007)

02 Feb 2007; Zac Medico <[e-mail]> +portage-2.1.2-r6.ebuild:
2.1.2-r6 revbump. Bugs #162453 and #147007 track fixes since 2.1.1.

Expected Results:  
A list of bugs that were fixed since 2.1.2-r5 only, instead of all bugs since the 2.1.2 release.

[Comment 1 Jakub Moc (RETIRED) 2007-02-03 12:12:11 UTC]

Yeah, we need changelog growing to MBs size apparently for people that can't check bugzilla... Kindly see /usr/share/doc/portage-${PF}/Changelog.bz2

[Comment 2 Wilbur Pan 2007-02-03 14:02:25 UTC]

You can mark this bug as invalid, but it doesn't change the fact that this style of documentation is completely inadequate.  

1.  To refer to /usr/share/doc/portage-${PF}/Changelog.bz2 would require installing the new version of portage to see this Changelog, when what is needed is to be able to identify what has changed BEFORE installing the updated version.  It would be one thing if this was a rarely used app. For an application as critical as portage, this information is very important.

2.  As far as bugzilla as a documentation source, currently I would have to look at all 15 bugs referenced to identify the two bugs that portage-2.1.2-r6 addresses.

Continuing the previous style of listing which bugs were fixed would be fine:

3 Jan 2007; Zac Medico <[e-mail]> +portage-2.1.2_rc4-r9.ebuild:
2.1.2_rc4-r9 revbump. This fixes bugs #9870, #50738, #69021, #88485,
#141867, #144380, #144445, #147785, #150051, #153755, #156865, and #157812.

[Comment 3 Jakub Moc (RETIRED) 2007-02-03 16:01:53 UTC]

Yay for rants, portage folks, enjoy...

[Comment 4 Zac Medico 2007-02-03 16:37:53 UTC]

(In reply to comment #2)
> 2.  As far as bugzilla as a documentation source, currently I would have to
> look at all 15 bugs referenced to identify the two bugs that portage-2.1.2-r6
> addresses.

Not necessarily.  You can also look at the bug activity:

http://bugs.gentoo.org/show_activity.cgi?id=162453

None of the recent fixes are anything really major.  There just a bunch of fixes for small but annoying issues.  I don't think most people are interested in knowing about all these little issues, but I think you can get everything you'd want to know from the tracker bug activity.

[Comment 5 Zac Medico 2007-02-05 23:24:35 UTC]

The changelog shows bugs fixed in 2.1.2-r8.