commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [ALL] fix site doc version so it agrees with release [was: [compress] Two issues with releasing the release]
Date Sun, 24 May 2009 13:16:52 GMT
Henri Yandell wrote:
> On Sat, May 23, 2009 at 11:30 PM, Phil Steitz <phil.steitz@gmail.com> wrote:
>
>   
>>> We're the victims of an experiment that was only half completed imo.
>>>
>>>       
>> +1.  I tend to remove the development reports when I cut RCs and roll
>> releases.  I also favor having the www website focussed on current
>> development, with prior release documentation linked - i.e., javadoc for the
>> last few releases linked in the nav.  I also like to include a fully
>> generated website with the distribution.
>>     
>
> Big downside of that is that:
>
> a) We have to start ditching the various GPL reports. Findbugs +
> Cobertura jump out.
>   
No great loss, IMO.  As I said, I view those as "development reports," 
so pull them out of RCs.
> b) It makes for very confusing documentation. The website and
> documentation should be in different contexts - the website for
> example is multi-release while documentation is per release.
>   
I agree with the spirit of this.  By cutting out the development 
reports, a simple maven site can include javadoc, user guide and any 
other documentation that should go with the release.  That is what I 
would like to bundle with the binary release.  Unless we do this, we 
have to keep full versioned docs (including user guides, etc.) on the 
www site, which is more of a pain, IMO.  The "workaround" that I 
recommend is that we ship a full site, stripped of development reports, 
with binary releases and keep javadoc and changelogs for the last few 
releases linked on www.  That is not too hard to do with what Maven 
provides today and satisfies the basic user need.
> c) Baking the website in the release adds an order of pain to the
> release going out - it's very nice (agile) to be able to not consider
> website issues as blocking when releasing a component.
>
>   
I guess it depends on the component.  In [math], I consider the user 
guide as part of the release,  which does add a little pain (not just at 
release time, but when closing issues).  For some (most?) other 
components, the javadoc is really the only documentation that counts.

Phil
> Hen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>   


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message