You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sebb <se...@gmail.com> on 2009/05/22 13:08:41 UTC
[ALL] fix site doc version so it agrees with release [was: [compress]
Two issues with releasing the release]
On 22/05/2009, Christian Grobmeier <gr...@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?
> Next dev. snapshot is 1.1.
>
> Cheers,
>
> Christian
>
>
> ---------------------------------------------------------------------
> 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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by Rahul Akolkar <ra...@gmail.com>.
On Fri, May 22, 2009 at 8:57 PM, sebb <se...@gmail.com> wrote:
> On 23/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>> On Fri, May 22, 2009 at 7:01 PM, sebb <se...@gmail.com> wrote:
>> > On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>> >> On Fri, May 22, 2009 at 9:14 AM, sebb <se...@gmail.com> wrote:
>> >> > On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>> >> >> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
>> >> >> > On 22/05/2009, Christian Grobmeier <gr...@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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by sebb <se...@gmail.com>.
On 23/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
> On Fri, May 22, 2009 at 7:01 PM, sebb <se...@gmail.com> wrote:
> > On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
> >> On Fri, May 22, 2009 at 9:14 AM, sebb <se...@gmail.com> wrote:
> >> > On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
> >> >> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
> >> >> > On 22/05/2009, Christian Grobmeier <gr...@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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by Rahul Akolkar <ra...@gmail.com>.
On Fri, May 22, 2009 at 7:01 PM, sebb <se...@gmail.com> wrote:
> On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>> On Fri, May 22, 2009 at 9:14 AM, sebb <se...@gmail.com> wrote:
>> > On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>> >> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
>> >> > On 22/05/2009, Christian Grobmeier <gr...@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). The "Project Reports" section therefore contains the bleeding
edge by design. If folks want release docs, they can look at the
"Releases" section.
> 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.
> 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).
-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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by sebb <se...@gmail.com>.
On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
> On Fri, May 22, 2009 at 9:14 AM, sebb <se...@gmail.com> wrote:
> > On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
> >> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
> >> > On 22/05/2009, Christian Grobmeier <gr...@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. Note that the header on the site is
0.10-SNAPSHOT; looks like the site was generated incorrectly.
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.
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.
>
> -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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by Rahul Akolkar <ra...@gmail.com>.
On Fri, May 22, 2009 at 9:14 AM, sebb <se...@gmail.com> wrote:
> On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
>> > On 22/05/2009, Christian Grobmeier <gr...@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.
-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
Re: [ALL] fix site doc version so it agrees with release [was: [compress]
Two issues with releasing the release]
Posted by Phil Steitz <ph...@gmail.com>.
Henri Yandell wrote:
> On Sat, May 23, 2009 at 11:30 PM, Phil Steitz <ph...@gmail.com> wrote:
>
>
>>> We're the victims of an experiment that was only half completed imo.
>>>
>>>
>> +1. I tend to remove the development reports when I cut RCs and roll
>> releases. I also favor having the www website focussed on current
>> development, with prior release documentation linked - i.e., javadoc for the
>> last few releases linked in the nav. I also like to include a fully
>> generated website with the distribution.
>>
>
> Big downside of that is that:
>
> a) We have to start ditching the various GPL reports. Findbugs +
> Cobertura jump out.
>
No great loss, IMO. As I said, I view those as "development reports,"
so pull them out of RCs.
> b) It makes for very confusing documentation. The website and
> documentation should be in different contexts - the website for
> example is multi-release while documentation is per release.
>
I agree with the spirit of this. By cutting out the development
reports, a simple maven site can include javadoc, user guide and any
other documentation that should go with the release. That is what I
would like to bundle with the binary release. Unless we do this, we
have to keep full versioned docs (including user guides, etc.) on the
www site, which is more of a pain, IMO. The "workaround" that I
recommend is that we ship a full site, stripped of development reports,
with binary releases and keep javadoc and changelogs for the last few
releases linked on www. That is not too hard to do with what Maven
provides today and satisfies the basic user need.
> c) Baking the website in the release adds an order of pain to the
> release going out - it's very nice (agile) to be able to not consider
> website issues as blocking when releasing a component.
>
>
I guess it depends on the component. In [math], I consider the user
guide as part of the release, which does add a little pain (not just at
release time, but when closing issues). For some (most?) other
components, the javadoc is really the only documentation that counts.
Phil
> Hen
>
> ---------------------------------------------------------------------
> 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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by Henri Yandell <fl...@gmail.com>.
On Sat, May 23, 2009 at 11:30 PM, Phil Steitz <ph...@gmail.com> wrote:
>> We're the victims of an experiment that was only half completed imo.
>>
>
> +1. I tend to remove the development reports when I cut RCs and roll
> releases. I also favor having the www website focussed on current
> development, with prior release documentation linked - i.e., javadoc for the
> last few releases linked in the nav. I also like to include a fully
> generated website with the distribution.
Big downside of that is that:
a) We have to start ditching the various GPL reports. Findbugs +
Cobertura jump out.
b) It makes for very confusing documentation. The website and
documentation should be in different contexts - the website for
example is multi-release while documentation is per release.
c) Baking the website in the release adds an order of pain to the
release going out - it's very nice (agile) to be able to not consider
website issues as blocking when releasing a component.
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [ALL] fix site doc version so it agrees with release [was: [compress]
Two issues with releasing the release]
Posted by Phil Steitz <ph...@gmail.com>.
Henri Yandell wrote:
> On Fri, May 22, 2009 at 6:14 AM, sebb <se...@gmail.com> wrote:
>
>> On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>>
>>> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
>>> > On 22/05/2009, Christian Grobmeier <gr...@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?
>>
>> (*) 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?
>>
>
> Sorry for replying on the other thread.
>
> A website is not documentation. We should remove the version and
> properly label 'Project Reports' as 'Latest Development Reports' or
> some such.
>
> We're the victims of an experiment that was only half completed imo.
>
+1. I tend to remove the development reports when I cut RCs and roll
releases. I also favor having the www website focussed on current
development, with prior release documentation linked - i.e., javadoc for
the last few releases linked in the nav. I also like to include a fully
generated website with the distribution.
Phil
> Hen
>
> ---------------------------------------------------------------------
> 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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by sebb <se...@gmail.com>.
On 23/05/2009, Henri Yandell <fl...@gmail.com> wrote:
> On Fri, May 22, 2009 at 6:14 AM, sebb <se...@gmail.com> wrote:
> > On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
> >> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
> >> > On 22/05/2009, Christian Grobmeier <gr...@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?
> >
> > (*) 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?
>
>
> Sorry for replying on the other thread.
>
> A website is not documentation.
Disagree. Many of the commons components would be all but unusable
without the documentation provided in the web-site.
> We should remove the version and
> properly label 'Project Reports' as 'Latest Development Reports' or
> some such.
There's still some information that needs to be provided to users
before they download a release. For example dependency information,
Java version and release notes. These are obviously dependent on the
release version.
> We're the victims of an experiment that was only half completed imo.
>
> Hen
>
>
> ---------------------------------------------------------------------
> 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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by Henri Yandell <fl...@gmail.com>.
On Fri, May 22, 2009 at 6:14 AM, sebb <se...@gmail.com> wrote:
> On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
>> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
>> > On 22/05/2009, Christian Grobmeier <gr...@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?
>
> (*) 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?
Sorry for replying on the other thread.
A website is not documentation. We should remove the version and
properly label 'Project Reports' as 'Latest Development Reports' or
some such.
We're the victims of an experiment that was only half completed imo.
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by sebb <se...@gmail.com>.
On 22/05/2009, Rahul Akolkar <ra...@gmail.com> wrote:
> On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
> > On 22/05/2009, Christian Grobmeier <gr...@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?
(*) 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?
> -Rahul
>
>
> ---------------------------------------------------------------------
> 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
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by Rahul Akolkar <ra...@gmail.com>.
On Fri, May 22, 2009 at 7:08 AM, sebb <se...@gmail.com> wrote:
> On 22/05/2009, Christian Grobmeier <gr...@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
-Rahul
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [ALL] fix site doc version so it agrees with release [was:
[compress] Two issues with releasing the release]
Posted by Henri Yandell <fl...@gmail.com>.
I realize this thread went the wrong direction.
Why the green? Just noticed Taglibs has the same problem (it uses the
Commons CSS :) ). Very ugly. Presumably we used to use a different
colour and the CSS has been changed?
Hen
On Fri, May 22, 2009 at 4:08 AM, sebb <se...@gmail.com> wrote:
> On 22/05/2009, Christian Grobmeier <gr...@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?
>
>> Next dev. snapshot is 1.1.
>>
>> Cheers,
>>
>> Christian
>>
>>
>> ---------------------------------------------------------------------
>> 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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org