Draft: simple update description guidelines

[Chris Weyl]

On Wed, Jan 28, 2009 at 4:58 PM, Kevin Kofler <kevin.kofler at chello.at> wrote:
> Chris Weyl wrote:
>> To-date, I haven't seen any comment back on my suggestion of pulling
>> the changelogs out automatically and providing a link + the package
>> URL link in the GUI.  If CPAN can make README's available like this,
>> why can't we?  And why isn't this a happy middle ground, providing
>> detailed upstream change information without another new manual task,
>> at least worthy of a try?
>
> Because upstreams' ways to communicate user-readable lists of changes vary
> wildly. Some keep ChangeLog in a user-readable format, some use a NEWS file
> in the source tarball, some have a changes.html page on their site which
> gets updated with each release, some have separate announcements for each
> release, on a new page for each release, some have newsitems on their front
> page in a Slashdot-style format and write the lists of changes in there and
> finally some don't have such summaries at all and it's your job as the
> maintainer to figure out what changed (and complain to upstream about the
> lack of documentation). There's just no way to get this right
> automatically.
>
> Throwing in an FSF-style changelog full of irrelevant changes like "fix typo
> in comment" isn't going to help anyone. And projects don't necessarily ship
> with a file called ChangeLog at all. There's plenty of names used, like
> ChangeLog.txt, NEWS, NEWS.txt, changes.txt, changes.html, changes.htm,
> WhatsNew.txt etc. (there's a lot more). And that's just those which have
> the changelog in the tarball, others have it on some website only (and
> there names vary even more widely, there are CMS URLs like
> index.php?module=changes&someargument=foobar&page=0).

This is kinda my point exactly.  Our maintainers didn't sign up to
sort through all that and write the equivalent of a legal brief for
each update, especially without any hard data showing that it's
needed; they signed up to maintain packages.

I also tend to think we're downplaying the intelligence of our users.
If they're smart enough to try to sort through the updates and
reasonably figure out what they do and don't want, I'm pretty sure
that if we give them the tools (package URL, direct pointer to any
changelog we can auto-find, etc), they'll be to make those decisions.
If they're not, well...  It doesn't really matter what we put in the
updates field, then.

> And also all this still doesn't provide the rationale *why* the update is
> being pushed.

And, of course, that's the other point: is this a back-door attempt to
require some sort of extended push justification, justification we've
never required before, or a sincere desire to give our users more
information?

                                        -Chris
-- 
Chris Weyl
Ex astris, scientia