From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from lists.gentoo.org ([140.105.134.102] helo=robin.gentoo.org)
	by nuthatch.gentoo.org with esmtp (Exim 4.43)
	id 1DxbL7-0004cG-83
	for garchives@archives.gentoo.org; Wed, 27 Jul 2005 02:08:09 +0000
Received: from robin.gentoo.org (localhost [127.0.0.1])
	by robin.gentoo.org (8.13.4/8.13.4) with SMTP id j6R27ITL001920;
	Wed, 27 Jul 2005 02:07:18 GMT
Received: from egr.msu.edu (jeeves.egr.msu.edu [35.9.37.127])
	by robin.gentoo.org (8.13.4/8.13.4) with ESMTP id j6R25fj1002081
	for <gentoo-dev@lists.gentoo.org>; Wed, 27 Jul 2005 02:05:42 GMT
Received: from [207.72.143.170] (207-72-143-170.dovers_res_net.spartan-net.net [207.72.143.170] (may be forged))
	(authenticated bits=0)
	by egr.msu.edu (8.13.4/8.13.4) with ESMTP id j6R25odf014545
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO)
	for <gentoo-dev@lists.gentoo.org>; Tue, 26 Jul 2005 22:05:54 -0400 (EDT)
Message-ID: <42E6EBFD.5000003@egr.msu.edu>
Date: Tue, 26 Jul 2005 22:05:49 -0400
From: Alec Warner <warnera6@egr.msu.edu>
User-Agent: Mozilla Thunderbird 1.0.2 (X11/20050704)
X-Accept-Language: en-us, en
Precedence: bulk
List-Post: <mailto:gentoo-dev@lists.gentoo.org>
List-Help: <mailto:gentoo-dev+help@gentoo.org>
List-Unsubscribe: <mailto:gentoo-dev+unsubscribe@gentoo.org>
List-Subscribe: <mailto:gentoo-dev+subscribe@gentoo.org>
List-Id: Gentoo Linux mail <gentoo-dev.gentoo.org>
X-BeenThere: gentoo-dev@gentoo.org
Reply-to: gentoo-dev@lists.gentoo.org
MIME-Version: 1.0
To: gentoo-dev@lists.gentoo.org
Subject: [gentoo-dev] Changelogs
X-Enigmail-Version: 0.90.2.0
X-Enigmail-Supports: pgp-inline, pgp-mime
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
X-Archives-Salt: b6db6da2-1bd2-4729-b55c-63ffd9970fcf
X-Archives-Hash: f25015b59bb7a7fc4c78ed47af791c99

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


Recent discussion on this ML and on the portage-ml as well as
#gentoo-portage regarding pkg_warn() and the basic concept behind it.
We talked about adding new functionality, about adding a warning section
to the ebuild or to the metadata.  However.  all of these tend to have
problems.  The dev won't write the extra function, duplication of data
in pkg_{post/pre}inst, mangling of metadata.xml.

Portage current features the -l switch, to show changelogs.  It works
pretty well to show changes in packages prior to emerging.  For example,
emerge -uDpvl world -> shows what will emerge then shows the changelogs
for each package.  For a very large set of packages the output can be
overwhelming, however all the changelogs are provided and the user at
least has data to parse through.

The problem is that the ebuild is where all the action is, and the
changelogs lay empty.  Users cannot run most ebuild functions prior to
emerging packages ( usually pkg_postinst() for migrating instructions ),
thus any important messages that need to be seen that deal with the
package are only seen after it is installed.  This is bad because the
user is not warned ahead of time about any issues ( new library
installed, breaks new processes that link to it ).

Basically this is a suggestion for developers to put more information in
the changelog.  You are ( usually ) the maintainer, you know what the
program can do, what problems it can cause.  Putting this information in
pkg_postinst() is good, but putting it in the changelog is better.
Believe it or not; users actually read the changelog and hope at times
that it provides valuable information about the package and not "marked
stable on foo ( #41975 )".

Marking it stable on an arch and knowing that moving to stable has the
potential to break stable systems should be noted in the changelog, even
if there is just a pointer to a website, or to the ebuild itself to read
the pkg_postinst() and figure out wtf is going to happen.

*Marches toward better changelogs since most of the current logs are
rather skimpy on any details*

- -Ajec
warnera6@egr.msu.edu
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iQIVAwUBQubrsWzglR5RwbyYAQI3dg/+KVFX4GctDzVjfhVDVDzGbx7q+T+0P+yf
AYOrsoWuFWcUh2/0FDV8z2aZ1P55M/SBWKgtFmkdMOGTUD34KGTZlyWMlcswxKfO
a3D43Dr1DQ6x66I2Gcf3VyHqpBgnPKgVhuNUiuFO8WD5N/W/sICLoTW415GEA7U7
jktDqrE+TDKBAdHvY2YaGD8iXZBX0zrS2v/1eeBLJ5/rSVVQfG9DICbMcRZ4lf5L
B6ktoarY5xjv6raE9wlZgrkjGpd7VoSn8yRnd10ekwftAlk1JKbAn8TIttWeMmYJ
9ZgLm/ZVjxAbzfoRhHjpw1nRb2q5oOeODfZQyOvlWFpZRhvMFySsDddfGsCbC2BS
Yf6pf8vKIMHRFLRSSupOl8agzHOm+CSGLHCpv+gs9sZ2eXzO2UjKqnN1VwoMO1sd
AJO/z28BvjqnBFU5WsTVmAxhuvziplrLTMfZP93k2VJ3zIni7NhKsLs4rJLnYbbP
xFg/Ji/YrZWwqXKFANYV2m/rw2HciKuFQzS2YmrZceAWjPz6s21m4yX6z+Hr1p+3
cu1TMIbZsg5ZA5V+nnmV1vfwW1fCLsyItOjYfv9IZi6JdupU22Lr3yR13wcUL6ZN
oFt3KmgLzZLjakXiIgICvKT9ZMKBMTkfkHh4qf6cxKmPHPan3Mi+5eBXmPWZ2oGQ
Q7gW3j/+Cps=
=Ymtl
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list