You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Benjamin Bentmann <be...@udo.edu> on 2009/08/03 15:08:12 UTC
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Hi Vincent,
> Author: vsiveton
> Date: Mon Aug 3 12:58:03 2009
> New Revision: 800341
>
> URL: http://svn.apache.org/viewvc?rev=800341&view=rev
> Log:
> MJAVADOC-248: Site 'Usage' page references 2.5 version of m-javadoc-p
>
> o fix it
>
> Modified: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
> URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt?rev=800341&r1=800340&r2=800341&view=diff
> ==============================================================================
> --- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt (original)
> +++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt Mon Aug 3 12:58:03 2009
> @@ -4,7 +4,7 @@
> Vincent Siveton
> Maria Odea Ching
> ------
> - 2008-07-31
> + 2009-08-03
> ------
>
> ~~ Licensed to the Apache Software Foundation (ASF) under one
> @@ -45,7 +45,6 @@
> <plugin>
> <groupId>org.apache.maven.plugins</groupId>
> <artifactId>maven-javadoc-plugin</artifactId>
> - <version>2.5</version>
> </plugin>
> </plugins>
Not locking down the plugin version is a bad practice but how can we
expect users to abandon this habbit if not even the official docs show
the proper plugin configuration? So how about filtering the document
instead and use ${project.version}?
Benjamin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Arnaud HERITIER <ah...@gmail.com>.
>
>
>>
> Not locking down the plugin version is a bad practice but how can we expect
> users to abandon this habbit if not even the official docs show the proper
> plugin configuration? So how about filtering the document instead and use
> ${project.version}?
>
>
+1
I think itshould be good thing to do in all our usage pages.
Arnaud.
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Brett Porter <br...@apache.org>.
On 03/08/2009, at 2:02 PM, Dennis Lundberg wrote:
> Brett Porter wrote:
>>
>> On 03/08/2009, at 11:23 AM, Vincent Siveton wrote:
>>
>>> 2009/8/3 Brett Porter <br...@apache.org>:
>>>> I would find that confusing. The filtering is automatic and is
>>>> just as
>>>> official...
>>>
>>> yes but it implies more work when you write doc...
>>
>> I am in favour of investing effort in writing the docs once to avoid
>> spending a bunch of time repeatedly answering questions later :)
>
> +1
>
> Let us put "Filter docs that uses POM snippets" on our pre-release
> todo
> list for plugins.
docck rule?
>
> We could also do a drive and fix all plugins at once. Sure, it will
> take
> some time, but then we don't have to worry about it anymore. At least
> not until we write new docs.
>
>>
>>>
>>> Vincent
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
>
> --
> Dennis Lundberg
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Dennis Lundberg <de...@apache.org>.
Brett Porter wrote:
>
> On 03/08/2009, at 11:23 AM, Vincent Siveton wrote:
>
>> 2009/8/3 Brett Porter <br...@apache.org>:
>>> I would find that confusing. The filtering is automatic and is just as
>>> official...
>>
>> yes but it implies more work when you write doc...
>
> I am in favour of investing effort in writing the docs once to avoid
> spending a bunch of time repeatedly answering questions later :)
+1
Let us put "Filter docs that uses POM snippets" on our pre-release todo
list for plugins.
We could also do a drive and fix all plugins at once. Sure, it will take
some time, but then we don't have to worry about it anymore. At least
not until we write new docs.
>
>>
>> Vincent
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Brett Porter <br...@apache.org>.
On 03/08/2009, at 11:23 AM, Vincent Siveton wrote:
> 2009/8/3 Brett Porter <br...@apache.org>:
>> I would find that confusing. The filtering is automatic and is just
>> as
>> official...
>
> yes but it implies more work when you write doc...
I am in favour of investing effort in writing the docs once to avoid
spending a bunch of time repeatedly answering questions later :)
>
> Vincent
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Vincent Siveton <vi...@gmail.com>.
2009/8/3 Brett Porter <br...@apache.org>:
> I would find that confusing. The filtering is automatic and is just as
> official...
yes but it implies more work when you write doc...
Vincent
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Brett Porter <br...@apache.org>.
On 03/08/2009, at 11:15 AM, Vincent Siveton wrote:
> Hi Brett,
>
> 2009/8/3 Brett Porter <br...@apache.org>:
>> I'm not sure you guys are talking about the same thing :)
>
> I hope
>
>> Vincent, he is pointing out that the config you have put into the
>> doc now
>> does not work (at least without a corresponding pluginManagement
>> section).
>> It's unclear from your response how you intend to fix that.
>> Personally, I
>
> Sorry if I was not clear, I propose to add a link to plugin-info.html
> ("the *official* conf) instead of copy plugin conf or filtering pages.
> The official conf for plugin version will be centralized to one place.
I would find that confusing. The filtering is automatic and is just as
official...
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Vincent Siveton <vi...@gmail.com>.
Hi Brett,
2009/8/3 Brett Porter <br...@apache.org>:
> I'm not sure you guys are talking about the same thing :)
I hope
> Vincent, he is pointing out that the config you have put into the doc now
> does not work (at least without a corresponding pluginManagement section).
> It's unclear from your response how you intend to fix that. Personally, I
Sorry if I was not clear, I propose to add a link to plugin-info.html
("the *official* conf) instead of copy plugin conf or filtering pages.
The official conf for plugin version will be centralized to one place.
Cheers,
Vincent
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Brett Porter <br...@apache.org>.
On 03/08/2009, at 11:00 AM, Vincent Siveton wrote:
> 2009/8/3 Benjamin Bentmann <be...@udo.edu>:
>> Well, enabling the doc filtering is a one-time task and I wouldn't
>> say it's
>> for nothing. The problem I see with those version-less POM snippets
>> is that
>> users just use them as is, without further thought. Nobody is going
>> to read
>> each and every doc page, people do some googling to find a solution
>> for
>
> Definitely agree all devs are lazy :)
> A link to one page that centralizes information is enough IMHO.
>
> In the past, when we wrote the plugins's documentation, we have not
> the plugin report so we rewrite the configuration. I think it is
> obsolete now.
> We need to force the user to use the conf defined in plugin-info.html.
>
> It implies that we *never* deploy a site snapshot but that it is
> another story!
I'm not sure you guys are talking about the same thing :)
Vincent, he is pointing out that the config you have put into the doc
now does not work (at least without a corresponding pluginManagement
section). It's unclear from your response how you intend to fix that.
Personally, I like the idea of filtering in the version for the cut-
and-paste crowd too.
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Vincent Siveton <vi...@gmail.com>.
2009/8/3 Benjamin Bentmann <be...@udo.edu>:
> Well, enabling the doc filtering is a one-time task and I wouldn't say it's
> for nothing. The problem I see with those version-less POM snippets is that
> users just use them as is, without further thought. Nobody is going to read
> each and every doc page, people do some googling to find a solution for
Definitely agree all devs are lazy :)
A link to one page that centralizes information is enough IMHO.
In the past, when we wrote the plugins's documentation, we have not
the plugin report so we rewrite the configuration. I think it is
obsolete now.
We need to force the user to use the conf defined in plugin-info.html.
It implies that we *never* deploy a site snapshot but that it is another story!
Cheers,
Vincent
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Benjamin Bentmann <be...@udo.edu>.
Vincent Siveton wrote:
> IMHO it will be an overhead for nothing...
Well, enabling the doc filtering is a one-time task and I wouldn't say
it's for nothing. The problem I see with those version-less POM snippets
is that users just use them as is, without further thought. Nobody is
going to read each and every doc page, people do some googling to find a
solution for their task, grab the XML bits of interest and expect their
builds to work. That is to say I believe this single page where we
recommend to lock down the plugin version will easily be overlooked.
From JIRA and IRC I can't fight the feeling that the practice of
locking down plugin versions is still not too common among users so I
believe it's valuable to promote this practice by having all our docs
demonstrate it.
Last but not least, there are plans to remove auto-versioning for POM
plugins in future Maven versions. That means version-less plugin blocks
in the POM will be rejected as an invalid model, i.e. the example
snippets will not only be bad practice, they will not work at all. If
users already fill JIRA tickets for outdated plugin versions in the
examples, I would imagine they do the same for non-working examples as
well...
Benjamin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r800341 - /maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/usage.apt
Posted by Vincent Siveton <vi...@gmail.com>.
Hi Benjamin,
2009/8/3 Benjamin Bentmann <be...@udo.edu>:
> Not locking down the plugin version is a bad practice but how can we expect
> users to abandon this habbit if not even the official docs show the proper
> plugin configuration? So how about filtering the document instead and use
> ${project.version}?
IMHO it will be an overhead for nothing...
All plugins have similar pages than [1]. I think we could for all
plugins add a link to this page for configuration instead of repeat
this kind of conf in the doc.
WDYT?
Cheers,
Vincent
[1] http://maven.apache.org/plugins/maven-javadoc-plugin/plugin-info.html
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org