mod_perl2 User's Guide
By Stas Bekman, Jim Brandt
By Stas Bekman, Eric Cholet
This doc clears the confusion regarding the need and the maintenance guidelines of Changes.pod files in the project.
All the modifications of every single file can be viewed via
log command. e.g., to check the history of this very file, one would
% svn log src/contribute/docs/changes_file.pod
Which will display all the commit logs, who has committed the change, who has submitted the changes, etc.
The Changes.pod document is not the same as the history of all changes. This document is for end user consumption, who is interested to know what are the major changes since the last time she read the documents. Or minor but important changes, like bug fixes.
Therefore the Changes.pod document is only needed when some sub-project goes through changes which will be of interest to the reader. Don't just add Changes.pod everywhere, until you really think it's needed.
The format of this document should be as dense as possible, so the reader can read through it fast and pin-point if there is something interesting to it.
There is no need to log the date every time the change is done ('svn log' has all the info). Though it's nice to group the changes by certain milestones, so let's say every few month a time stamp is added in front of the group of the changes since the last timestamp and new changes will go to the new group. The change entries in the docs/1.0/guide/Changes.pod is a good example of that. In addition it used to add a version number for each milestone, which is very optional now.
This file should have the latest changes on the top.
Usually we have a separate Changes.pod file for each sub-set of the documents. If you feel that the changes for a few sub-sets nested in the same super-set of docs can be maintained in one file, have only one Changes.pod. Later if this file becomes too overloaded and its added value is getting diminished, split it into a few Changes.pod files placed in each sub-set. Or if you think that this will happen in the near future do this from the beginning to avoid the slicing work later.
If you are the maintainer of the document, you don't have to credit each change done by you, with your name, simply leave the change entry un-credited, which automatically implies that you did that.
If someone commits something to the document maintained by someone else simply mark it with your name e.g. [Thomas Klausner]. Those who commit all the time, should pick some short (nick?)name that will distinguish them from others and make their changes with it. e.g [thomas]. The idea is to have the changes file with as little noise as possible.
There is a special case where we want to credit people who contributed
very minor fixes, which don't deserve a separate changes entry. In
this case just have a special entry like
Minor fixes, where you
simply list the names of those who contributed because we want to give
credits to everybody. Again the docs/1.0/guide/Changes.pod file
perfectly demonstrates that.
See docs/1.0/guide/Changes.pod as a good example.
A typical entry looks like this:
=head1 ??? * books: Fixed some things and then other things, and then some other things bla bla bla. [John Doe E<lt>john.doe (at) aol.comE<gt>] * file: Added some content. [stas] * otherfile: updated the "Maintenance" section, adding references to bla bla bla [other person] =head1 Sat Nov 12 22:05:23 CET 2002 * docs::index : moved tutorials to "Other documentation" [stas] * performance: minor corrections [thomas]
Please try to keep things correctly aligned here (ie. the first characters on each line should be vertically aligned with eachother), as this file will most often be viewed as text.
As you can see, we try to collect a number of changes, then timestamp the document like a "version".
You can use the Changes_template.pod as a starting point.