Draft: simple update description guidelines

Kevin Kofler kevin.kofler at chello.at
Thu Jan 29 00:58:10 UTC 2009


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).

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

        Kevin Kofler




More information about the devel mailing list