I got a *lot* CVS commit messages in my inbox this morning. It's
great to see JDOM moving again. However, maybe we can cut down on the
volume a little. In particular I just noted a batch of commit
messages for JavaDoc HTML files.It's normally considered best
practice *not* to store generated files such as JavaDoc in your
version control system. Andy Hunt and Dave Thomas discuss this on p.
10 of Pragmatic Version Control (The Pargmatic Programmers LLC, 2003):
If we store all the things needed to build the project, does that mean
that we should also be storing all the generated files? For example,
we might run JavaDoc to generate the API documentation for our source
tree. Should that documentation be stored in the version control
system's repository?
The simple answer is "no." If a generate file can be reconstituted
from other files, then storing it is simply duplication. Why is this
duplication bad? It isn't because we're worried about wasting disk
space. It's because we don't want things to get out of step. If we
store the source and the documentation, and then change the source,
the documentation is now outdated. If we forget to update it and check
it back in, we've now got misleading documentation in our repository.
So in this case, we'd want to keep a single source of the information,
the source code.
So I recommend we delete all the generated JavaDoc from the CVS tree.
Obviously this doesn't apply to things like package.html files that
are used to generate the overviews and are independent of the source
code.
At 3:28 AM -0700 2/6/04, nobody wrote:
>****************************************
>Date: Fri Feb 6, 2004 @03:28:07 MST
>Author:
>
>Update of /home/cvs/jdom-site/docs/apidocs
>In directory chimbo:/tmp/cvs-serv22247
>
>Modified Files:
>allclasses-frame.html allclasses-noframe.html
>constant-values.html deprecated-list.html help-doc.html
>index.html overview-frame.html overview-summary.html
>overview-tree.html packages.html serialized-form.html
>Log Message:
>Checking in javadocs for jdom-b10-rc1 so they'll be easily viewable
>on the website.
>
>-jh-
>
>===================================================================
>File: allclasses-frame.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/allclasses-frame.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: allclasses-noframe.html Status: Up-to-date
>
> Working revision: 1.4 Fri Feb 6 10:27:55 2004
> Repository revision: 1.4
> /home/cvs/jdom-site/docs/apidocs/allclasses-noframe.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.3)
>
>===================================================================
>File: constant-values.html Status: Up-to-date
>
> Working revision: 1.4 Fri Feb 6 10:27:55 2004
> Repository revision: 1.4
> /home/cvs/jdom-site/docs/apidocs/constant-values.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.3)
>
>===================================================================
>File: deprecated-list.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/deprecated-list.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: help-doc.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/help-doc.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: index.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/index.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: overview-frame.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/overview-frame.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: overview-summary.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/overview-summary.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: overview-tree.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/overview-tree.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: packages.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/packages.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>===================================================================
>File: serialized-form.html Status: Up-to-date
>
> Working revision: 1.7 Fri Feb 6 10:27:55 2004
> Repository revision: 1.7
> /home/cvs/jdom-site/docs/apidocs/serialized-form.html,v
>
> Existing Tags:
> jdom_1_0_b9 (revision: 1.6)
>
>_______________________________________________
>To control your jdom-commits membership:
>http://lists.denveronline.net/mailman/options/jdom-commits/youraddr@(protected)
--
Elliotte Rusty Harold
elharo@(protected)
Effective XML (Addison-Wesley, 2003)
http://www.cafeconleche.org/books/effectivexml
http://www.amazon.com/exec/obidos/ISBN%3D0321150406/ref%3Dnosim/cafeaulaitA
_______________________________________________
To control your jdom-interest membership:
http://lists.denveronline.net/mailman/options/jdom-interest/youraddr@(protected)
