commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rahul Akolkar <rahul.akol...@gmail.com>
Subject Re: [ALL] fix site doc version so it agrees with release [was: [compress] Two issues with releasing the release]
Date Sat, 23 May 2009 12:24:38 GMT
On Fri, May 22, 2009 at 8:57 PM, sebb <sebbaz@gmail.com> wrote:
> On 23/05/2009, Rahul Akolkar <rahul.akolkar@gmail.com> wrote:
>> On Fri, May 22, 2009 at 7:01 PM, sebb <sebbaz@gmail.com> wrote:
>>  > On 22/05/2009, Rahul Akolkar <rahul.akolkar@gmail.com> wrote:
>>  >> On Fri, May 22, 2009 at 9:14 AM, sebb <sebbaz@gmail.com> wrote:
>>  >>  > On 22/05/2009, Rahul Akolkar <rahul.akolkar@gmail.com> wrote:
>>  >>  >> On Fri, May 22, 2009 at 7:08 AM, sebb <sebbaz@gmail.com>
wrote:
>>  >>  >>  > On 22/05/2009, Christian Grobmeier <grobmeier@gmail.com>
wrote:
>>  >>  >>  >> > Another minor glitch I noticed just now. All
pages seem to include a
>>  >>  >>  >>  > green "1.1-SNAPSHOT" in the grey headline,
which may come in via the
>>  >>  >>  >>  > generating style sheet or an ant property
(I didn't check how the site
>>  >>  >>  >>  > is generated).
>>  >>  >>  >>
>>  >>  >>  >>
>>  >>  >>  >> Thanks, but it looks like "know issue":
>>  >>  >>  >>
>>  >>  >>  >>  http://wiki.apache.org/commons/CreatingReleases
:
>>  >>  >>  >>
>>  >>  >>  >>  "E.3 Deploy the Site
>>  >>  >>  >>
>>  >>  >>  >>  Run mvn site-deploy to deploy the site - please
note that you are
>>  >>  >>  >>  deploying the site of the next development snapshot.
"
>>  >>  >>  >
>>  >>  >>  > That's awful - surely there has to be a better way to
do this?
>>  >>  >>  >
>>  >>  >>  > Would it work if the site-deploy was run from a checkout
of the release tag?
>>  >>  >>  >
>>  >>  >>
>>  >>  >> <snip/>
>>  >>  >>
>>  >>  >>  Yes, but often, there is value to having latest docs online
as well,
>>  >>  >>  and pointers to docs for more than one release. My SOP is:
>>  >>  >>
>>  >>  >>  a) On release, checkout tag, deploy site
>>  >>  >>  b) Move docs (Javadocs, perhaps a user guide) to a release
area
>>  >>  >>  c) Checkout trunk, add nav menu to release area, deploy site
>>  >>  >>  d) Maintain last few (3?) rolling release areas
>>  >>  >>
>>  >>  >
>>  >>  > OK, but it seems to me that the main documentation should relate
to
>>  >>  > the current release; past or future documentation can be made
>>  >>  > available as well, but it is critical that the current documentation
>>  >>  > is readily available. (*)
>>  >>  >
>>  >>  > Are there any examples/documentation to show exactly how this is
done?
>>  >>  >
>>  >>
>>  >> <snip/>
>>  >>
>>  >>  No docs, just the list in the email above :-) You can look at the
>>  >>  [SCXML] or [digester] site to get some idea of what was done. Adjust
>>  >>  recipe per taste.
>>  >
>>  > The above mentioned sites go part-way towards solving the problem, in
>>  > that the Javadoc, releases notes and source are available for multiple
>>  > releases, however the "Project Reports" section only relates to one
>>  > version, and in the case of SCXML the Javadoc sub-section is actually
>>  > for 0.10 rather than 0.90.
>>
>> <snip/>
>>
>>  I always keep the site at trunk, so the homepage includes latest fixes
>>  and "Who is using it?" list is current etc. (you mean 0.9, not 0.90
>>  BTW).
>
> I see. Confusing numbering scheme...
>
<snip/>

Not for me. But it can potentially trip people up I'm aware. Details
are in "Dissecting the Release Number" on this page:

  http://commons.apache.org/releases/versioning.html


>>  The "Project Reports" section therefore contains the bleeding
>>  edge by design. If folks want release docs, they can look at the
>>  "Releases" section.
>
> But the Releases section does not include some pages which may vary
> between releases, such as:
> * Userguide
> * Dependencies
> * Checkstyle
> * Unit tests
> * Source XRef
> * Test Xref
>
<snap/>

For those who want all that, a full site copy can be made (instead of
just Javadocs, release notes etc.). Here is one example where I deemed
this worthy:

  http://shale.apache.org/1.0.4/


>>
>>
>>  > Note that the header on the site is
>>  > 0.10-SNAPSHOT; looks like the site was generated incorrectly.
>>
>> <snap/>
>>
>>  No, it is intentionally that way.
>>
>>
>>
>>  > Digester has 2.1-SNAPSHOT in the header although the current release
>>  > is 2.0, so presumably the common "Project Reports" and "Project Info"
>>  > sections relate to 2.1-SNAPSHOT.
>>  >
>>  > I'm afraid neither of those are satisfactory in my opinion.
>>
>> <snip/>
>>
>>  On the contrary, I'm quite happy with this.
>>
>
> As a developer, yes, maybe it is nice to have the latest information,
> but that should be on developer pages, not on the general user pages.
>
<snip/>

Consider "Project Reports" to be developer pages (along Hen's comment).


> Before I started doing work on Commons, I had a lot of difficulty as a
> user trying to find details on the various libraries used by JMeter,
> so that I could update the dependencies for each release. I still find
> it unnecessarily complicated, even though I know more about how things
> are organised.
>
> It should be really easy to find out the current releases for a given
> component, what versions of Java each requires, and what the
> dependencies are. This is not the case with many of the Commons sites
> at the moment.
>
<snap/>

Suggest an alternative, document the m2 steps. If its not a lot more
work and most think its an improvement over the state of affairs, I'll
use it from the next release.


>>
>>  > However, it must be possible to do it, because BeanUtils (for example)
>>  > shows the same version in the header as the current release, and also
>>  > has documentation for two earlier releases.
>>
>> <snap/>
>>
>>  It just means BeanUtils never pushed out the site after the 1.8.0
>>  release (because it may not have been necessary, maybe no site related
>>  fixes yet).
>
> But the problem is that the instructions seem to ensure that the site
> never corresponds with the current release, even on the day the
> release is made. Christian followed the "correct" procedure yet
> Compress site is for 1.1-SNAPSHOT even though there have not yet been
> any changes since 1.0.
>
<snip/>

There is no need to update the site / redeploy from trunk if nothing
has changed (à la BeanUtils). Procedure (if by that you mean the
CreatingReleases wiki page) may need tweaking to that effect.

-Rahul

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


Mime
View raw message