You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gary Gregory <ga...@gmail.com> on 2013/12/11 05:05:20 UTC
Re: Snapshot vs. release sites.
Hi All:
I am going to try why I propose on [codec]. Stay tuned...
Gary
On Thu, Nov 14, 2013 at 8:46 PM, sebb <se...@gmail.com> wrote:
> On 12 November 2013 05:17, Henri Yandell <fl...@gmail.com> wrote:
> > On Fri, Nov 8, 2013 at 4:24 AM, sebb <se...@gmail.com> wrote:
> >
> >> On 7 November 2013 17:45, Phil Steitz <ph...@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
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
Spring Batch in Action <http://www.manning.com/templier/>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: Snapshot vs. release sites.
Posted by Gary Gregory <ga...@gmail.com>.
On Tue, Dec 10, 2013 at 11:05 PM, Gary Gregory <ga...@gmail.com>wrote:
> Hi All:
>
> I am going to try why I propose on [codec]. Stay tuned...
>
Check https://commons.apache.org/proper/commons-codec/
An alternative layout would be to do what http://bootstrapdocs.com/ does: a
simple top level page will links to all versions, including the current
one, and additionally for us the SNAPSHOT version.
Gary
>
> Gary
>
>
> On Thu, Nov 14, 2013 at 8:46 PM, sebb <se...@gmail.com> wrote:
>
>> On 12 November 2013 05:17, Henri Yandell <fl...@gmail.com> wrote:
>> > On Fri, Nov 8, 2013 at 4:24 AM, sebb <se...@gmail.com> wrote:
>> >
>> >> On 7 November 2013 17:45, Phil Steitz <ph...@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
>>
>>
>
>
> --
> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
> Spring Batch in Action <http://www.manning.com/templier/>
> Blog: http://garygregory.wordpress.com
> Home: http://garygregory.com/
> Tweet! http://twitter.com/GaryGregory
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
Spring Batch in Action <http://www.manning.com/templier/>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory