ChangeLog (was Gnome Web Plone Sprint)

[Murray Cumming <murrayc murrayc com>]

On Mon, 2008-10-27 at 18:15 -0700, Jonathan Wilde wrote:
> It would definitely be good to have more documentation in commit
> messages.  It would be helpful for the users that wanted to help, but
> didn't have the time to figure out how.
> 
> @Murray
> What types of information would you prefer in the log messages?  How,
> for example, would you rewrite "Fixed conflict marks in the css file."
> to make it better?  Would you prefer to provide the exact path to the
> css file rather than just saying, "css file"?  What other
> modifications would you make?

ChangeLog messages are fairly standard. A changelog message would look
something like this:

2008-10-28  Jonathan Wilde  <speedbreeze gmail com>

	* somewhere/someplace/something.css: Fixed conflict marks.
	yadda, yadda, actually explain briefly what on earth that means.
	* somewhere/someplaceelse/thing.py: do_something(): Foo the goo 
	when we have hoo to do.

There are ChangeLog messages in some of the sub-directories, where
people thought that makes sense. You should use them where they exist
instead of the top-level one.

I recommend that you use moap's "moap changelog prepare -c" command to
create the ChangeLog entry. There are some other scripts listed here if
you don't like moap:
http://live.gnome.org/DeveloperUtilities

Here is an example from our current www.gnome.org site:
http://svn.gnome.org/viewvc/gnomeweb-wml/trunk/ChangeLog?view=markup
and here is an example from one of my C++ projects:
http://svn.gnome.org/viewvc/glom/trunk/ChangeLog?view=markup

Note that any two people will have slight differences of opinions about
what exactly ChangeLogs should look like, but I'm not interested in
that.

The other Plone people who have been working on the system know about
this already, though they tend to forget.

-- 
murrayc murrayc com
www.murrayc.com
www.openismus.com