[jdom-interest] Re: [jdom-commits] CVS Update: jdom-site/docs/apidocs

[Jason Hunter]

Our case is different than what they're talking about.  I keep the 
jdom.org website content in CVS.  When I want to push new Javadocs to 
the public website, how I do it is generate them on the client, copy 
them into the jdom-site module, check them into CVS, and then check out 
the current jdom-site into the restricted server area.  That way you can 
always see what was the published version of http://jdom.org at any time 
in the past and can view it easily by checking out jdom-site.  You don't 
risk being out of sync because it's part of a specific publishing 
process.  In the jdom module itself Javadocs are not checked in.

What I wish is that CVS would send one message per check-in, not per 
directory of files per check-in.  Hope SVN fixes this.

-jh-

Elliotte Rusty Harold wrote:

> 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@yourhost.com 
>>
> 
>