Javadoc build should include a timestamp and/or the svn revision number in a visible location.

• Key: DERBY-220
• Type: Improvement
• Status: Closed
• Resolution: Fixed
• Priority: Minor
• Assignee: Dyre Tjeldvoll
• Reporter: Andrew McIntyre
• Component/s: Build tools
• Affects Version/s: 10.1.1.0
• Fix Version/s: 10.1.1.0

Description

In order to easily identify when a specific set of javadoc was built, and from what source, it would be useful to include a timestamp and/or the svn revision number at the time the javadoc is built. The footer is an excellent location to place this information, as it is visible on every generated page.

Comments

[Dyre Tjeldvoll]

I've thought a bit about this, and I'm wondering about exactly which revision and timestamp you want:

a) Do you want the most recent revision for the repository, or the most recent revision in which something (in Derby) changed? The first one is already available as the changeversion property, and could easily be added to the javadoc footer.
(I guess that, ideally, one would want the revision in which something that affects the javadoc was changed. But I don't think that's feasible...)

b) About the timestamp; do you mean the the time when the javadoc command was run, or the time when the revision in a) was committed to the repository?

Consider the output from "svn info", standing in trunk:

dt136804@atum10~/local/d_rby-220$ svn info
Path: .
URL: https://svn.apache.org/repos/asf/incubator/derby/code/trunk
Repository UUID: 13f79535-47bb-0310-9956-ffa450edef68
Revision: 170751
--> This is the same as the "changedversion" property

Node Kind: directory
Schedule: normal
Last Changed Author: bandaram
Last Changed Rev: 170695
--> This is the last revision in which something in trunk changed

Last Changed Date: 2005-05-18 03:15:14 +0200 (Wed, 18 May 2005)
--> And this is the corresponding date

Properties Last Updated: 2005-05-13 16:10:24 +0200 (Fri, 13 May 2005)
------------------------

It is fairly simple to add the raw output from "svn info" to the javadoc footer, but this is probably overkill. It also clutters up the footer and takes up quite a bit of screen real-estate. It would be trivial to write a shell-script that filters the output, but this would not be portable. One could let a java program to do the filtering, but one would still be relying on the output from "svn info" being stable... I don't know if it is.

A different approach would be to include the Subversion keywords (LastChangedRevision and LastChangedDate or Id) in the javadoc description for each class. You would have to change every file (and remember to set the svn:keyword property), but this could be done by a script. The diff would be huge, though...

Does the reporter (or anyone else) have any comments on this?

[Andrew McIntyre]

For the svn revision, it should be the svn revision of the view from which the javadoc was built. This represents most closely the state of the javadoc at the time it is built. The svn revision can be retrieved using the svnversion command. See the jar build for an example of how the changenumber property is set. In fact, you could probably just reuse the initjars target to set the changenumber.

For the timestamp, I suggest using Ant's internal timestamp properties. the <tstamp> task is called to set these properties in the init target. It's just a matter of using them.

So, all that might need to be done is to call the right init targets before the build, and add ${tstamp} and ${changenumber} to the footer text.

As for using the Subversion keywords in the java source files, I suppose it's probably most useful for determining who last changed the particular file, but I think for purposes of dating the build, putting the timestamp and revision in the footer achieves the same thing much less intrusively.

[Dyre Tjeldvoll]

A screenshot showing the javadoc with timestamp and revision.

[Dyre Tjeldvoll]

Thank you for your comments Andrew, they were very helpful. Please note that in my first comment I mistakenly referred to
the property "changedversion" when I meant "changenumber". There is no property called "changedversion", sorry about the confusion.

I have added a preliminary patch and a screenshot. Feel free to review the patch, but please don't commit it until I have had a chance to run derbyall, (derbyall currently fails on a clean trunk, so I'll have to wait until that's sorted out...).

[Dyre Tjeldvoll]

New diff based on the latest revision

[Dyre Tjeldvoll]

I have tried to run derbyall for about a week, but some tests always fail.
I hope that a committer can look at derbyall_report.txt and perhaps consider the patch anyway...

[Andrew McIntyre]

Committed, revision 179401.