diff options
Diffstat (limited to 'src/echangelog/echangelog.pod')
| -rw-r--r-- | src/echangelog/echangelog.pod | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/src/echangelog/echangelog.pod b/src/echangelog/echangelog.pod new file mode 100644 index 0000000..192af8d --- /dev/null +++ b/src/echangelog/echangelog.pod @@ -0,0 +1,136 @@ +=head1 NAME + +echangelog - Gentoo: update portage ChangeLogs + +=head1 SYNOPSIS + +echangelog [ I<text> ] + +=head1 DESCRIPTION + +This tool provides an easy way to create or update portage ChangeLogs +in Gentoo. The tool scans the current directory, which is assumed to +be a package directory such as /usr/portage/app-editors/vim, finds +what files have been changed or added, and inserts the appropriate +entry to ChangeLog. If I<text> is not provided on the command-line, +echangelog prompts for it. + +All modifications should occur before running echangelog so that it +can include the appropriate file information in the ChangeLog entry. +For example, you should run "cvs add" on your files, otherwise +echangelog won't know those files are part of the update. + +If your text would cause the ChangeLog entry to exceed 80 columns, it +will be rewrapped to keep the ChangeLog neat. If you need special +formatting in the ChangeLog, then you can either (1) run echangelog +with no text on the command-line, and make sure that your text won't +be too wide, (2) edit the ChangeLog manually. If you prefer (2), I'd +recommend something like "echangelog blah" so that the header lines +are computed correctly, then edit and change "blah" to your preferred +text. + +In addition to updating the ChangeLog, echangelog will automatically +update the copyright year of all out-of-date ebuilds, as well as the +ChangeLog itself. These updates are included in the diff displayed by +echangelog when it finishes its work. + +=head1 OPTIONS + +Presently echangelog is simple enough that it supplies no options. +Probably I'll add B<--help> and B<--version> in the future, but for +now it's enough to track the gentoolkit version. + +=head1 EXAMPLES + +To create a ChangeLog for a completely new package. The header is +parsed from skel.ebuild. + + $ cvs add metalog-0.1.ebuild + cvs server: use 'cvs commit' to add this file permanently + + $ echangelog 'New ebuild, thanks to Harvey McGillicuddy' + --- ChangeLog 1969-12-31 19:00:00.000000000 -0500 + +++ ChangeLog.new 2003-02-23 14:04:06.000000000 -0500 + @@ -0,0 +1,9 @@ + +# ChangeLog for app-admin/metalog + +# Copyright 2000-2003 Gentoo Technologies, Inc.; Distributed under the GPL v2 + +# $Header$ + + + +*metalog-0.1 (23 Feb 2003) + + + + 23 Feb 2003; Aron Griffis <agriffis@gentoo.org> metalog-0.1.ebuild : + + New ebuild, thanks to Harvey McGillicuddy + + + +To bump a revision. Note you need to "cvs add" so that echangelog +will notice the new file. + + $ cvs add metalog-0.1-r1.ebuild + cvs server: use 'cvs commit' to add this file permanently + + $ echangelog 'Bump revision to fix bug #999' + --- ChangeLog 2003-02-23 14:04:06.000000000 -0500 + +++ ChangeLog.new 2003-02-23 14:07:48.000000000 -0500 + @@ -2,6 +2,11 @@ + # Copyright 2000-2003 Gentoo Technologies, Inc.; Distributed under the GPL v2 + # $Header$ + + +*metalog-0.1-r1 (23 Feb 2003) + + + + 23 Feb 2003; Aron Griffis <agriffis@gentoo.org> metalog-0.1-r1.ebuild : + + Bump revision to fix bug #999 + + + *metalog-0.1 (23 Feb 2003) + + 23 Feb 2003; Aron Griffis <agriffis@gentoo.org> metalog-0.1.ebuild : + +For a multi-line entry, omit the command-line arg. + + $ echangelog + Please type the log entry, finish with ctrl-d + Bump revision to fix bug #999. Necessary to bump the revision because + the problem appears at run-time, not compile-time. This should also + give users the updated default configuration file. + --- ChangeLog 2003-02-23 14:09:12.000000000 -0500 + +++ ChangeLog.new 2003-02-23 14:12:43.000000000 -0500 + @@ -2,6 +2,13 @@ + # Copyright 2000-2003 Gentoo Technologies, Inc.; Distributed under the GPL v2 + # $Header$ + + +*metalog-0.1-r1 (23 Feb 2003) + + + + 23 Feb 2003; Aron Griffis <agriffis@gentoo.org> metalog-0.1-r1.ebuild : + + Bump revision to fix bug #999. Necessary to bump the revision because + + the problem appears at run-time, not compile-time. This should also + + give users the updated default configuration file. + + + *metalog-0.1 (23 Feb 2003) + + 23 Feb 2003; Aron Griffis <agriffis@gentoo.org> metalog-0.1.ebuild : + +=head1 ENVIRONMENT VARIABLES + +=over + +=item ECHANGELOG_USER + +If echangelog can't figure out your username for the entry, you should +set ECHANGELOG_USER. For example, export ECHANGELOG_USER="Aron +Griffis <agriffis@gentoo.org>" + +=back + +=head1 NOTES + +As of the most recent version of echangelog (when this man-page +appeared), echangelog puts all new entries at the top of the file +instead of finding the appropriate *version line within the file. +This is because that "new" ChangeLog format was never agreed upon by +the Gentoo developers. Unfortunately the existence of both formats +will undoubtedly cause much confusion. + +This also means that the examples above are wrong, since I just copied +them from some old email. However they're not much wrong. ;-) + +This tool was written by Aron Griffis <agriffis@gentoo.org>. Bugs +found should be filed against me at http://bugs.gentoo.org/ |