commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@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 00:57:09 GMT
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...

>  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

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

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.

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

>
>  -Rahul
>
>
>
>  >
>  >>
>  >>  -Rahul
>  >>
>  >>
>  >>
>  >>  > (*) In the case of Compress, the 1.1-SNAPSHOT docs are (currently) the
>  >>  > same as 1.0, but how is the user to know that?
>  >>  >
>  >>
>  >>
>
>  ---------------------------------------------------------------------
>  To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>  For additional commands, e-mail: dev-help@commons.apache.org
>
>

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


Mime
View raw message