shiro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Les Hazlewood <lhazlew...@apache.org>
Subject Re: Shiro Spring Cleaning!
Date Wed, 08 May 2013 00:58:28 GMT
Thanks for the feedback Glen.

The .x approach is interesting.  One of the things that I really value with
other open source projects with versioned documentation is "show me the
docs for the exact version I'm using so I know what I'm getting".  The .x
approach might be a happy medium.

My initial idea was that there wouldn't be doc maintenance on the point
releases.  They are 'cut' when you cut a release and really left alone,
pretty much like API docs.  The only maintenance is calling a script when
you cut a release to copy the contents to a permanent directory and it's
pretty much left alone.  But this has the downside that if a doc edit for
the latest version is also valid for previous point releases, you have to
merge that edit with the previous releases and generate again.

Since we try really hard to follow APR versioning guidelines w/ Shiro, I
think it would be very rare that we'd have documentation that is relevant
for 1.3.3 that isn't also valid for 1.3.1, so the .x might be the best
angle.

Thanks for the idea!

Les

On Tue, May 7, 2013 at 7:03 AM, Glen Mazza <glen.mazza@gmail.com> wrote:

> On 04/21/2013 05:31 PM, Les Hazlewood wrote:
>
>  Additionally, these docs should live in perpetuity.  This way, as
>> Shiro end-user, I know if I'm using Shiro 2.0.5 for example, I know I
>> only need to go to the 2.0.5 docs and I don't have to worry about
>> extraneous or invalid documentation that doesn't affect me.  So I
>> would expect to see something like this:
>>
>> http://shiro.apache.org/docs/**1.2.2/<http://shiro.apache.org/docs/1.2.2/>
>> http://shiro.apache.org/docs/**2.0.0/<http://shiro.apache.org/docs/2.0.0/>
>> ...
>> http://shiro.apache.org/docs/**2.0.5/<http://shiro.apache.org/docs/2.0.5/>
>> etc.
>>
>>
> That seems like a lot of maintenance work for a volunteer project, I don't
> think most devs can afford to spend inordinate amounts on time on
> non-technical stuff like that.  Instead of needing to replicate 2.0.5,
> 2.0.4, 2.0.3, etc., perhaps just having docs for major release versions
> (1.2.x, 2.x, etc.) would be best.  How Karaf does docs:
> http://karaf.apache.org/index/**documentation.html<http://karaf.apache.org/index/documentation.html>with
the URL having "latest" in it (i.e., "latest-2.3.x") so it's always
> good may be a good approach.
>
> Glen
>
>

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