commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: Snapshot vs. release sites.
Date Wed, 11 Dec 2013 13:23:43 GMT
On Tue, Dec 10, 2013 at 11:05 PM, Gary Gregory <garydgregory@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 <sebbaz@gmail.com> wrote:
>
>> 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
>>
>>
>
>
> --
> 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

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