You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@creadur.apache.org by Robert Burrell Donkin <rd...@apache.org> on 2012/05/06 14:52:44 UTC
Switch to CMS ... ?
The next stage of the graduation hand-over is setting up the
infrastructure for Apache Creadur TLP. This includes the website.
I think there's generally positive feelings about the CMS, excepting
committing Maven generated sites. As a user, I find the Maven sites for
releases are useful. So, I suggest switching to the CMS and dropping
the Maven sites for anything other than releases.
If we're going to switch to the CMS, it will save some effort if we ask
infrastructure to set it up for the new TLP domain.
Opinions? Objections?
Robert
Re: Switch to CMS ... ?
Posted by Mark Struberg <st...@yahoo.de>.
+1 we aim for the same in OpenWebBeans.
CMS is easy to maintain for end user documentation, samples, guides, explanation etc.
But the maven site also has some really useful documentation:
* xref
* javadoc
* TODO report, etc
Eagerly waiting for a elaborated solution.
LieGrue,
strub
----- Original Message -----
> From: Robert Burrell Donkin <rd...@apache.org>
> To: rat-dev@incubator.apache.org
> Cc:
> Sent: Saturday, May 12, 2012 8:33 PM
> Subject: Re: Switch to CMS ... ?
>
> On 05/07/12 11:04, Gavin McDonald wrote:
>
> <snip>
>
>>> I think there's generally positive feelings about the CMS,
> excepting
>>> committing Maven generated sites. As a user, I find the Maven sites for
>>> releases are useful. So, I suggest switching to the CMS and dropping
>>> the Maven sites for anything other than releases.
>>
>> +1
>>
>> And Maven support is improving.
>
> This looks promising[1] :-)
>
> Robert
>
> [1] https://blogs.apache.org/infra/entry/apache_cms_and_external_build
>
Re: Switch to CMS ... ?
Posted by Robert Burrell Donkin <rd...@apache.org>.
On 05/07/12 11:04, Gavin McDonald wrote:
<snip>
>> I think there's generally positive feelings about the CMS, excepting
>> committing Maven generated sites. As a user, I find the Maven sites for
>> releases are useful. So, I suggest switching to the CMS and dropping
>> the Maven sites for anything other than releases.
>
> +1
>
> And Maven support is improving.
This looks promising[1] :-)
Robert
[1] https://blogs.apache.org/infra/entry/apache_cms_and_external_build
RE: Switch to CMS ... ?
Posted by Gavin McDonald <ga...@16degrees.com.au>.
> -----Original Message-----
> From: Robert Burrell Donkin [mailto:rdonkin@apache.org]
> Sent: Sunday, 6 May 2012 10:23 PM
> To: rat-dev@incubator.apache.org
> Subject: Switch to CMS ... ?
>
> The next stage of the graduation hand-over is setting up the
infrastructure
> for Apache Creadur TLP. This includes the website.
>
>
> I think there's generally positive feelings about the CMS, excepting
> committing Maven generated sites. As a user, I find the Maven sites for
> releases are useful. So, I suggest switching to the CMS and dropping
> the Maven sites for anything other than releases.
+1
And Maven support is improving.
>
> If we're going to switch to the CMS, it will save some effort if we ask
> infrastructure to set it up for the new TLP domain.
+1
Gav...
>
> Opinions? Objections?
>
> Robert
Re: Switch to CMS ... ?
Posted by Robert Burrell Donkin <rd...@apache.org>.
On 05/09/12 09:18, Jochen Wiedmann wrote:
> My feeling is that this means we'll need to maintain two documentation
> sets in the future. Wouldn't be happy about that.
Hopefully not...
AIUI Apache is moving towards hosting all websites using the CMS, so in
the future we're likely to have much smoother Maven integration[1].
The way I hope that the CMS will work is by hand crafting top level
(Apache Creadur) pages using the CMS[2], and then products (like rat and
whisker) either
* generate their sites (using Maven, say) and publish then through the
CMS (eg [3][4])
* or hand craft them (eg [5])
But until Maven support is smooth, we just update the generated sites
rarely...
Would this be good enough...?
Robert
[1] https://blogs.apache.org/infra/entry/apache_cms_and_external_build
[2] http://rat.staging.apache.org/rat/
[3] http://rat.staging.apache.org/rat/rat/
[4] http://rat.staging.apache.org/rat/whisker/
[5] http://rat.staging.apache.org/rat/tentacles/
Re: Switch to CMS ... ?
Posted by Jochen Wiedmann <jo...@gmail.com>.
My feeling is that this means we'll need to maintain two documentation
sets in the
future. Wouldn't be happy about that.
On Sun, May 6, 2012 at 2:52 PM, Robert Burrell Donkin
<rd...@apache.org> wrote:
> The next stage of the graduation hand-over is setting up the infrastructure
> for Apache Creadur TLP. This includes the website.
>
>
> I think there's generally positive feelings about the CMS, excepting
> committing Maven generated sites. As a user, I find the Maven sites for
> releases are useful. So, I suggest switching to the CMS and dropping the
> Maven sites for anything other than releases.
>
> If we're going to switch to the CMS, it will save some effort if we ask
> infrastructure to set it up for the new TLP domain.
>
> Opinions? Objections?
>
> Robert
--
"Bildung kommt von Bildschirm und nicht von Buch, sonst hieße es ja Buchung."
Dieter Hildebrandt
Re: Switch to CMS ... ?
Posted by Robert Burrell Donkin <rd...@apache.org>.
On 05/07/12 03:31, sebb wrote:
> On 6 May 2012 19:45, Robert Burrell Donkin<rd...@apache.org> wrote:
<snip>
>> Checking generated Maven sites into the CMS (eg [2]) produces lots of commit
>> messages (eg [3]), and is a little fiddly.
<snip>
> I had the same problem with JMeter Javadoc when it was in SVN; I
> solved that by post-processing the html files to remove the dates in
> the comments.
> The same could probably be done in the Maven pom if required.
Cool :-)
I suspect it's possible to wrangle the line ending foo as well
>>>> If we're going to switch to the CMS, it will save some effort if we ask
>>>> infrastructure to set it up for the new TLP domain.
<snip>
>>> For Maven sites that are generally only updated with each new release,
>>> the fact that Maven sites cannot be built piecemeal is not an issue,
>>> so is it worth the conversion effort?
>>
>>
>> Rat is sparsely documented, but I had hoped to work on some new,
>> user-centered content in the CMS and leave the existing stuff for releases.
>
> Unless it is going to change much between releases, it could still be
> done by Maven at release time.
+1
> However, there might be some restrictions imposed by CMS or Infra as
> to which URLs can be used for Maven and non-Maven generated site
> files.
>
> Might be an idea to run the plan past infra before doing much work.
+1
>> We need some form of cohesive top level site for Apache Creadur, hopefully
>> with some more documentation for users. The consensus seemed to be that
>> using the CMS fits this well, and allows some products to use Maven and some
>> to use the CMS for their documentation (by checking the Maven generated
>> sites into CMS).
>
> For new content, CMS is probably a good choice.
+1
>> Having tried it for a while, never me nor Stefan are particular keen[1]
>> about regularly checking in Maven generated sites. I'd be happy just
>> checking in the Maven generated documentation for each release.
>
> Indeed, Maven-generated sites are best suited for release time docs.
+1
Robert
Re: Switch to CMS ... ?
Posted by sebb <se...@gmail.com>.
On 6 May 2012 19:45, Robert Burrell Donkin <rd...@apache.org> wrote:
> On 05/06/12 16:04, sebb wrote:
>>
>> On 6 May 2012 13:52, Robert Burrell Donkin<rd...@apache.org> wrote:
>>>
>>> The next stage of the graduation hand-over is setting up the
>>> infrastructure
>>> for Apache Creadur TLP. This includes the website.
>>>
>>>
>>> I think there's generally positive feelings about the CMS, excepting
>>> committing Maven generated sites. As a user, I find the Maven sites for
>>> releases are useful. So, I suggest switching to the CMS and dropping the
>>> Maven sites for anything other than releases.
>>
>>
>> Not sure what you mean by that.
>
>
> (I'm still trying - and failing - to be meaningful and concise...)
>
>
>> How can there be a CMS site and a separate Maven site?
>> What URLs will these be using?
>
>
> We were experimenting [1] with checking in Maven sites...
>
> Checking generated Maven sites into the CMS (eg [2]) produces lots of commit
> messages (eg [3]), and is a little fiddly.
AFAICT, most of the commit message flood at [3] is because Javadoc
embeds a timestamp comment in the generated output.
I don't think that is entirely Maven's fault, though of course Maven
does not support rebuilding only the changed part of a site.
[Unfortunately using -Dmaven.javadoc.skip does not quite work, as
Maven creates an empty apidocs/index.html file]
I had the same problem with JMeter Javadoc when it was in SVN; I
solved that by post-processing the html files to remove the dates in
the comments.
The same could probably be done in the Maven pom if required.
>
> [1]
> http://mail-archives.apache.org/mod_mbox/incubator-rat-dev/201204.mbox/%3C4F8037FE.7050302%40blueyonder.co.uk%3E
> [2] http://rat.staging.apache.org/rat/rat/
> [3]
> http://mail-archives.apache.org/mod_mbox/incubator-rat-commits/201204.mbox/%3C20120407124344.BB6C523889BB%40eris.apache.org%3E
>
>
>>> If we're going to switch to the CMS, it will save some effort if we ask
>>> infrastructure to set it up for the new TLP domain.
>>>
>>> Opinions? Objections?
>>
>>
>> I think the CMS works well for sites that need frequent updates of
>> parts of the site.
>> For example, the main ASF site.
>>
>> Conversion to Markdown format can be a non-trivial exercise; although
>> there are some scripts, their output still needs some tweaking.
>> And there are some features of HTML which are not directly supported
>> by Markdown (e.g. numbered lists using alpha).
>>
>> For Maven sites that are generally only updated with each new release,
>> the fact that Maven sites cannot be built piecemeal is not an issue,
>> so is it worth the conversion effort?
>
>
> Rat is sparsely documented, but I had hoped to work on some new,
> user-centered content in the CMS and leave the existing stuff for releases.
Unless it is going to change much between releases, it could still be
done by Maven at release time.
However, there might be some restrictions imposed by CMS or Infra as
to which URLs can be used for Maven and non-Maven generated site
files.
Might be an idea to run the plan past infra before doing much work.
> We need some form of cohesive top level site for Apache Creadur, hopefully
> with some more documentation for users. The consensus seemed to be that
> using the CMS fits this well, and allows some products to use Maven and some
> to use the CMS for their documentation (by checking the Maven generated
> sites into CMS).
For new content, CMS is probably a good choice.
> Having tried it for a while, never me nor Stefan are particular keen[1]
> about regularly checking in Maven generated sites. I'd be happy just
> checking in the Maven generated documentation for each release.
Indeed, Maven-generated sites are best suited for release time docs.
> Robert
>
> [1]
> http://mail-archives.apache.org/mod_mbox/incubator-rat-dev/201204.mbox/%3C87lim5las5.fsf%40v35516.1blu.de%3E
Re: Switch to CMS ... ?
Posted by Robert Burrell Donkin <rd...@apache.org>.
On 05/06/12 16:04, sebb wrote:
> On 6 May 2012 13:52, Robert Burrell Donkin<rd...@apache.org> wrote:
>> The next stage of the graduation hand-over is setting up the infrastructure
>> for Apache Creadur TLP. This includes the website.
>>
>>
>> I think there's generally positive feelings about the CMS, excepting
>> committing Maven generated sites. As a user, I find the Maven sites for
>> releases are useful. So, I suggest switching to the CMS and dropping the
>> Maven sites for anything other than releases.
>
> Not sure what you mean by that.
(I'm still trying - and failing - to be meaningful and concise...)
> How can there be a CMS site and a separate Maven site?
> What URLs will these be using?
We were experimenting [1] with checking in Maven sites...
Checking generated Maven sites into the CMS (eg [2]) produces lots of
commit messages (eg [3]), and is a little fiddly.
[1]
http://mail-archives.apache.org/mod_mbox/incubator-rat-dev/201204.mbox/%3C4F8037FE.7050302%40blueyonder.co.uk%3E
[2] http://rat.staging.apache.org/rat/rat/
[3]
http://mail-archives.apache.org/mod_mbox/incubator-rat-commits/201204.mbox/%3C20120407124344.BB6C523889BB%40eris.apache.org%3E
>> If we're going to switch to the CMS, it will save some effort if we ask
>> infrastructure to set it up for the new TLP domain.
>>
>> Opinions? Objections?
>
> I think the CMS works well for sites that need frequent updates of
> parts of the site.
> For example, the main ASF site.
>
> Conversion to Markdown format can be a non-trivial exercise; although
> there are some scripts, their output still needs some tweaking.
> And there are some features of HTML which are not directly supported
> by Markdown (e.g. numbered lists using alpha).
>
> For Maven sites that are generally only updated with each new release,
> the fact that Maven sites cannot be built piecemeal is not an issue,
> so is it worth the conversion effort?
Rat is sparsely documented, but I had hoped to work on some new,
user-centered content in the CMS and leave the existing stuff for releases.
We need some form of cohesive top level site for Apache Creadur,
hopefully with some more documentation for users. The consensus seemed
to be that using the CMS fits this well, and allows some products to use
Maven and some to use the CMS for their documentation (by checking the
Maven generated sites into CMS).
Having tried it for a while, never me nor Stefan are particular keen[1]
about regularly checking in Maven generated sites. I'd be happy just
checking in the Maven generated documentation for each release.
Robert
[1]
http://mail-archives.apache.org/mod_mbox/incubator-rat-dev/201204.mbox/%3C87lim5las5.fsf%40v35516.1blu.de%3E
Re: Switch to CMS ... ?
Posted by sebb <se...@gmail.com>.
On 6 May 2012 13:52, Robert Burrell Donkin <rd...@apache.org> wrote:
> The next stage of the graduation hand-over is setting up the infrastructure
> for Apache Creadur TLP. This includes the website.
>
>
> I think there's generally positive feelings about the CMS, excepting
> committing Maven generated sites. As a user, I find the Maven sites for
> releases are useful. So, I suggest switching to the CMS and dropping the
> Maven sites for anything other than releases.
Not sure what you mean by that.
How can there be a CMS site and a separate Maven site?
What URLs will these be using?
> If we're going to switch to the CMS, it will save some effort if we ask
> infrastructure to set it up for the new TLP domain.
>
> Opinions? Objections?
I think the CMS works well for sites that need frequent updates of
parts of the site.
For example, the main ASF site.
Conversion to Markdown format can be a non-trivial exercise; although
there are some scripts, their output still needs some tweaking.
And there are some features of HTML which are not directly supported
by Markdown (e.g. numbered lists using alpha).
For Maven sites that are generally only updated with each new release,
the fact that Maven sites cannot be built piecemeal is not an issue,
so is it worth the conversion effort?
AIUI, a Maven generated site can still be published with svnpubsub.
> Robert