Colin Marquardt: +Category "Developer Documentation"

2006-06-20T13:49:24Z

+Category "Developer Documentation"

← Older revision		Revision as of 13:49, 20 June 2006
Line 33:		Line 33:

	Are there any when it is OK to check in without a Bug or Patch tracker's being open ...		Are there any when it is OK to check in without a Bug or Patch tracker's being open ...

			[[Category:Developer Documentation]]

Conversion script: link fix

2006-01-22T02:32:52Z

link fix

New page

A Change Log for a project is a semi-structured plain text file in the root of the project's directory which is a latest-first history of what has been done. It can act as a very high level 'Undo' mechanism. It should consist of several segments which look like this: <pre>
2005-06-20 Ted Gould <ted@gould.cx>

* src/desktop.cpp, src/desktop.h, src/document-private.h,
src/document.cpp, src/document.h, src/extension/effect.h,
src/extension/implementation/script.cpp:

Adding in a signal to show that the document is being reconstructed from
another document. This is used by the scripting extensions implementation
to say to the desktops that they need to save their object references
as strings instead of pointers -- and then recreate them when the
reconstruction is complete.

* src/extension/prefdialog.cpp: Making "OK" have focus.

* src/verbs.cpp, src/verbs.h: Some prototype code to start making verbs
sensitive or not. Not tied in to anything currently.
</pre>

and consist of the the Date, the Maintainer[[/Committer/Author]] and a list of entries; the entries consist of a list of files affected and a high level description of what the commit did. The layout of each entry depends a little on how long the description needs to be. Concise guidance is: "An entry should have an asterisk, the name of the changed file, and then in parentheses the name of the changed functions, variables or whatever, followed by a colon. Then describe the changes you made to that function or variable."

Some projects have most formal guidelines for filling in a Change Log. See

* The GNU standard for [http://www.gnu.org/prep/standards/standards.html#Change-Logs Change Logs].
* [http://www.rtems.com/cvswrite.html#checkin Checking in a change], which recommends inserting the whole of the Change Log Entry into the CVS Log, something that I am far from certain is widespread practice.
* A detailed account of [http://www.red-bean.com/cvs2cl/changelogs.html CVS Logs and [[ChangeLogs]]], which also suggests that the CVS Log should match the Change Log Entry, but implies that it should be briefer.

In summary, the Change Log is part of the living metadata of a project and should be maintained in such a way that the route that that the code base got to its current state can always be ascertained.

Any comments specific to Inkscape ...

Are there circumstances when a Bug or Patch number must be included in the CVS Log or Chnagelog ...

Are there any when it is OK to check in without a Bug or Patch tracker's being open ...

ChangeLog - Revision history

Colin Marquardt: +Category "Developer Documentation"

Conversion script: link fix