commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Henri Yandell <flame...@gmail.com>
Subject Re: Snapshot vs. release sites.
Date Tue, 12 Nov 2013 05:17:06 GMT
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?


> >>
> >> 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.

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]

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

Hen

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message