[tcljava-dev] How to write a ChangeLog entry (was: Patch for bug 121678)

[Mo D. <md...@cy...>]

On Wed, 8 Nov 2000 tcl...@li... wrote:

> Hello,
> 
> > Be sure to include a ChangeLog entry too :)
> And here are my questions: What is the best tool
> to work with ChangeLog (Emacs most probably)?
> Should the patch contain the ChangeLog diff, too?

Working with ChangeLog entries is really easy.
You can use emacs if you like, it kind of helps
as it does some formatting for you.

You don't need to send a diff of the ChangeLog
entry. Just paste it in at the top as regular
text.

Just start with the date:

2000-11-08

Then add 2 spaces and your name:

2000-11-08  Christian Krone

Then 2 more spaces and your email address:

2000-11-08  Christian Krone  <kri...@sq...>

Finally: skip a line and then indent with a TAB
followed by a * a space and the file name:

2000-11-08  Christian Krone  <kri...@sq...>

	* filexyz.c

At this point you need to decide if the changes you
made could have more to do with a given function
or if they are just sort of generic to the file.

If the changes are not really focused on a single
function, just add a : and the description of
the change. Like so:

2000-11-08  Christian Krone  <kri...@sq...>
  
        * filexyz.c: Fix some comments.

Now, if you changed some things that have to do
with a function or a set of functions, then
you would list those functions in parens. Like so:

2000-11-08  Christian Krone  <kri...@sq...>

        * filexyz.c (func1, func2): Change return
	values of func1 and func2, negative numbers
	should no longer be returned.

Also, if you have a whole bunch of changes that
are the same, you don't need to list them for
every single file. Just make a comment for
a set of files, like so:

2000-11-08  Christian Krone  <kri...@sq...>
  
        * file1:
	* file2:
	* file3: Update copyright text.


It is not hard, one just needs to get into the habit
of doing it. It really helps 6 months down the road
when you have forgotten what you did earlier. There
is no better way to track down when a bug was
introduced.

Mo DeJong
Red Hat Inc