commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: Snapshot vs. release sites.
Date Fri, 15 Nov 2013 01:46:04 GMT
On 12 November 2013 05:17, Henri Yandell <flamefew@gmail.com> wrote:
> On Fri, Nov 8, 2013 at 4:24 AM, sebb <sebbaz@gmail.com> wrote:
>
>> On 7 November 2013 17:45, Phil Steitz <phil.steitz@gmail.com> wrote:
>> > On 11/6/13 10:11 PM, Henri Yandell wrote:
>> >> On Wed, Nov 6, 2013 at 7:53 AM, Gary Gregory <garydgregory@gmail.com>
>> wrote:
>> >>
>> >>> Hi All:
>> >>>
>> >>> I find it unhelpful and confusing at times to see Commons sites for
>> >>> -SNAPSHOT version.
>> >>>
>> >>> I'd prefer to be able to browse a whole site for any released version.
>> This
>> >>> is especially handy when I want to find information for some older
>> version
>> >>> I must work with through an inherited dependency.
>> >>>
>> >> The tail is wagging the dog (ie: Maven is leading us astray).
>>
>> This is nothing to do with Maven per se.
>> It's just a question of what source is used to build the website.
>>
>>
> There's the tail wagging us. Why is source (of the component) used to build
> the website?

I meant: which version of the source xdocs are used to build the site.

It does not have to be trunk; it could be the tag or a branch (which
is what we do for JMeter).

>
>> >>
>> >> The notion of a website having a version is absurd :)  [other than its
>> own
>> >> svn/git versioning]
>>
>> > +1 - I tend to agree with the site == head approach that we have
>> > pretty much always taken.  I like the Tomcat approach of making
>> > versioned site content available for past releases, but that is a
>> > pain to maintain and I am loathe to ask more from Commons RMs atm or
>> > to clutter svn with ever more little maven-generated files.  For
>> > most Commons components, there is not much beyond the javadoc
>> > anyway, which in most cases is already published for old releases.
>>
>> Forget about Commons for a moment.
>>
>> Consider Maven Plugin websites.
>>
>> Would they be useful if they only showed the documentation for the
>> unreleased head version of the plugin?
>>
>> No, of course not; it's essential the the user can readily find
>> documentation for the current release.
>> It would be nice if docs were also available for selected earlier
>> releases as well, but that is a separate issue.
>
>
> If we assume that users cannot manage documentation on their own, which I
> think is fair, then it's essential the user can readily find the
> documentation for the release they are using.

+1

> I think every component's site should be akin to (assume lots of
> cross-referenced linking):
>
> index.html -> Boilerplate blurb. Latest release info.
> releases.html -> Info about every release.
> docs/** -> Docs for each release. ie) Javadoc + User Guide; though if we
> wanted to also bundle quality docs we could (but I think it's pointless).
> download/** -> Download each release [obviously would be mirror structure
> etc]

That looks fine to me.

> None of those have anything to do with versions of source.

Huh?
At the very least the docs for each release should relate to the
source version for the release.

> Hen

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


Mime
View raw message