FS#7231 - guidline for ChangeLog file

Attached to Project: Pacman
Opened by Attila (attila) - Tuesday, 22 May 2007, 05:23 GMT
Last edited by Xavier (shining) - Friday, 08 February 2008, 11:42 GMT
Task Type Feature Request
Category Documentation
Status Closed
Assigned To Aaron Griffin (phrakture)
Xavier (shining)
Dan McGee (toofishes)
Architecture All
Severity Low
Priority Normal
Reported Version 0.8 Voodoo
Due in Version 3.1.2
Due Date Undecided
Percent Complete 100%
Votes 1
Private No

Details

I suggest that there be a small guideline how the ChangeLog could look because if we don't do it now we risk that everybody have to make his own thoughts.

Here is an example from my rpm based distribution on my server which could be a base for an discussion under the devs (Comment for the devs: My intention is only to give you a help and not to say that is has to look in this way):

* Do Mär 01 2007 cthiel@suse.de
- updated smart-trunk.patch to r857
- added smart-show-changelog.patch by Mauricio Teixeira and Davodet Olivier
(http://tracker.labix.org/issue244)
- added smart-fix-archscore-add-disable-biarch-option.patch,
smart-broken-repo-without-summary-or-description-workaround.diff and
smart-better-x86_64-support.patch by Pascal Bleser (fixes #242782)
- added experimental command "newer" by Pascal Bleser

* Mi Jan 31 2007 cthiel@suse.de
- readded smart-trunk.patch (r856)

* Di Jan 16 2007 cthiel@suse.de
- update to final 0.50 release
o Changed the transaction algorithm to make Smart able to survive massive
whole-distribution upgrades with good results, and in acceptable
timings.
o Changed the way that priorities are considered by the transaction
mechanism, so that tracking individual packages from arbitrary
repositories is actually much more predictable and manageable.
o Fixed leak that made packages never get deallocated when loading from a
disk cache.
o New '--dump' option to install/remove/upgrade commands. It outputs the
list of packages for requested transaction.
o Support for ETA during downloads in graphical and text modes
o Swedish translation
o Traditional Chinese translation
o Spanish translation
o Several bugs fixed
o More tests
This task depends upon

Closed by  Xavier (shining)
Friday, 08 February 2008, 11:42 GMT
Reason for closing:  Implemented
Additional comments about closing:  implemented by commit 7069b96173aa
Comment by Dan McGee (toofishes) - Wednesday, 23 May 2007, 04:40 GMT
This feature is primarily intended to grab the package's already included ChangeLog file, and not so much place the burden on the packager to create their own.
Comment by Attila (attila) - Wednesday, 23 May 2007, 05:06 GMT
The lines above be an example of what all could be possible. But at example the last lines with the update be very informative but from my view it is enough to say "update to final 0.50 release" and nothing more because the url of a package is only one "pacman -Qi" far away.

I don't want that any dev will have a burden by creating this file. Documentation, and a changelog is nothing else as documentate what you have done and why, is a help for users and devs.

Comment by Alessio Bolognino (mOLOk) - Wednesday, 23 May 2007, 15:47 GMT
This is the ChangeLog I added to deluge:

(49429)$> pacman -Qc deluge
deluge 0.5.0-3
Changelog:

2007-05-21: deluge-0.5.0-3

* Rebuild against boost-1.34.0-1
* Now the pixmaps is bigger (128x128), looks better in the docks

It is more or less what I wrote in the cvs commit comment: it isn't too verbose, but
I think it is useful because users can understand why I updated the package.
As Attila said, the ChangeLog of the application can be found on pacman -Qi foo | grep ^URL
Comment by Aaron Griffin (phrakture) - Wednesday, 23 May 2007, 19:01 GMT
I think I agree that the ChangeLog should be for arch specific updates. I was unsure originally what the intent was (furgalware feature initially).

If we do go with the arch specific changes, we should probably follow the GNU standards fairly closely. The style is as follows:

----------------8<-------------------
2007-05-23 Aaron Griffin <aaronmgriffin@gmail.com>
* Logged into flyspray
* Added a comment to bug #7231
* ChangeLog.proto: begin prototype file for ABS

2007-01-01 Aaron Griffin <aaronmgriffin@gmail.com>
* Ate some cake
---------------->8-------------------
Comment by Alessio Bolognino (mOLOk) - Wednesday, 30 May 2007, 14:58 GMT
I agree, what about this? (it's more or less what Frugalware guys use):
----------------------------8<-----------------------
2007-05-30 Alessio Bolognino <molok@aur.archlinux.org>
* $pkgname-$pkgver-$pkgrel-$CARCH
added something
moved that in another package

2007-05-29 Alessio Bolognino <molok@aur.archlinux.org>
* $pkgname-$pkgver-$((pkgrel-1))-$CARCH
splitted foo
added a makedep
----------------------------8<-----------------------
Comment by Aaron Griffin (phrakture) - Wednesday, 30 May 2007, 16:13 GMT
Yeah, another quick thing to point out, specific files should be referenced if not the PKGBUILD... that is:

* gcc4.2.patch: Added for compilation

Or something to that effect. Lets just ignore the PKGBUILD prefix because 90% of the changes will probably be for that.
Comment by Xavier (shining) - Friday, 08 February 2008, 07:31 GMT
Does this work ? :
http://projects.archlinux.org/git/?p=pacman.git;a=commitdiff;h=7069b96173aa256d1c2eaed2d21811639e10e566
Comment by Roman Kyrylych (Romashka) - Friday, 08 February 2008, 08:26 GMT
Looks good to me.
I think we should write only significant changes to changelog, e.g. build options changes, but not just "bumped pkgrel" otherwise some packages' changelogs won't have much useful info except a ton of "bumped pkgrel".
Comment by Xavier (shining) - Friday, 08 February 2008, 10:27 GMT
Yes of course, just saying "bumped pkgrel" is totally pointless, there is no reason to write a ChangeLog at all in this case.
Probably only people who are willing to explain / list their changes will use a changelog.
So this can be closed?
Comment by Roman Kyrylych (Romashka) - Friday, 08 February 2008, 11:29 GMT
yep, it's implemented now

Loading...