You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Brett Porter <br...@apache.org> on 2006/06/19 15:47:02 UTC
Plugin documentation standard
Hi,
Just thought I'd break this one out. This needs to be converted to a
guide - which is one of the tasks I'll list at the end.
(this is MNG-1987, btw)
* Required POM Elements
- modelVersion, version, group ID, artifact ID, packaging (required
anyway to build)
- name
- description
- url
- issueManagement
- prerequisites > maven (I think it's good to make people think about this)
- inceptionYear
- mailingLists (just a warning if missing as I guess there might not be
one, though we should have some other contact details - do general
contact details fit a "list" description?)
- license
- scm (warning if missing, may not be OSS!)
- organization
- plugin report must be configured
* Plugin configuration
- each @parameter field must have a description. Not required if
@readonly or @component
- Class level should have a description.
* Documents
- plugins must have an /index.html (from apt, xdoc, html etc). Not
generated automatically
- plugins must have a /usage.html, where the standard use case is
described. The recommended lifecycle phases should be listed. This will
almost be boilerplate (just some common configuration items, how to
include it in the POM, and whether it usually needs executions or not).
It will probably repeat for each goal available.
- plugins should have examples/*.html for individual use cases.
- plugins should have a FAQ page for common questions, issues, and
misunderstandings
Consider this example:
- use case:
http://maven.apache.org/plugins/maven-release-plugin/introduction.html
- specific examples:
http://maven.apache.org/plugins/maven-release-plugin/howto.html (should
be broken out into examples/dryRun.apt, etc)
* Site descriptor
- navigation must include the link to the usage and the examples under that
* Reports
- Plugin must have javadoc, jxr and changelog reports
* General guidelines
- Always be able to publish the latest and greatest. Mark new features
with the version they were introduced. Mark caveats in certain versions.
- The Jetty6 and Cargo plugins are the level of information we are
looking for.
* Tasks (any volunteers? If so, please create a JIRA and grab it (and
drop a reply here to say so - eventually we'll get these all in
regardless though)
- convert the above to a guide on the Maven website
- add any missing checks to the docck plugin
- wire up the docck plugin to all maven plugins
- pilot plugins. Some of these have gone into JIRA already and been
assigned.
- rework the plugin reference page (a separate discussion, MPLUGIN-7 is
a starting point). This should be reworked not to overwrite index.html
- create an archetype for a compliant plugin
- add @since tag to plugin fields (it's standard javadoc so we can dual
purpose it, but we need to acknowledge it in the descriptor)
Any additional thoughts?
- Brett
--
Brett Porter <br...@apache.org>
Apache Maven - http://maven.apache.org/
Better Builds with Maven - http://library.mergere.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Plugin documentation standard
Posted by Brett Porter <br...@apache.org>.
Here's some additions, sorry I missed these:
# must have link to the API docs of of additional types (eg
MavenArchiveConfiguration)
# must describe how the configuration of some elements affects others,
where applicable (for example, surefire's suiteXmlFiles disables the
includes/excludes options)
# must document relationship with other plugins
- Brett
On 19/06/2006 11:47 PM, Brett Porter wrote:
> Hi,
>
> Just thought I'd break this one out. This needs to be converted to a
> guide - which is one of the tasks I'll list at the end.
>
> (this is MNG-1987, btw)
>
> * Required POM Elements
>
> - modelVersion, version, group ID, artifact ID, packaging (required
> anyway to build)
> - name
> - description
> - url
> - issueManagement
> - prerequisites > maven (I think it's good to make people think about this)
> - inceptionYear
> - mailingLists (just a warning if missing as I guess there might not be
> one, though we should have some other contact details - do general
> contact details fit a "list" description?)
> - license
> - scm (warning if missing, may not be OSS!)
> - organization
> - plugin report must be configured
>
> * Plugin configuration
>
> - each @parameter field must have a description. Not required if
> @readonly or @component
> - Class level should have a description.
>
> * Documents
>
> - plugins must have an /index.html (from apt, xdoc, html etc). Not
> generated automatically
> - plugins must have a /usage.html, where the standard use case is
> described. The recommended lifecycle phases should be listed. This will
> almost be boilerplate (just some common configuration items, how to
> include it in the POM, and whether it usually needs executions or not).
> It will probably repeat for each goal available.
> - plugins should have examples/*.html for individual use cases.
> - plugins should have a FAQ page for common questions, issues, and
> misunderstandings
>
> Consider this example:
> - use case:
> http://maven.apache.org/plugins/maven-release-plugin/introduction.html
> - specific examples:
> http://maven.apache.org/plugins/maven-release-plugin/howto.html (should
> be broken out into examples/dryRun.apt, etc)
>
> * Site descriptor
>
> - navigation must include the link to the usage and the examples under that
>
> * Reports
>
> - Plugin must have javadoc, jxr and changelog reports
>
> * General guidelines
>
> - Always be able to publish the latest and greatest. Mark new features
> with the version they were introduced. Mark caveats in certain versions.
> - The Jetty6 and Cargo plugins are the level of information we are
> looking for.
>
> * Tasks (any volunteers? If so, please create a JIRA and grab it (and
> drop a reply here to say so - eventually we'll get these all in
> regardless though)
> - convert the above to a guide on the Maven website
> - add any missing checks to the docck plugin
> - wire up the docck plugin to all maven plugins
> - pilot plugins. Some of these have gone into JIRA already and been
> assigned.
> - rework the plugin reference page (a separate discussion, MPLUGIN-7 is
> a starting point). This should be reworked not to overwrite index.html
> - create an archetype for a compliant plugin
> - add @since tag to plugin fields (it's standard javadoc so we can dual
> purpose it, but we need to acknowledge it in the descriptor)
>
> Any additional thoughts?
>
> - Brett
>
>
--
Brett Porter <br...@apache.org>
Apache Maven - http://maven.apache.org/
Better Builds with Maven - http://library.mergere.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Plugin documentation standard
Posted by Brett Porter <br...@apache.org>.
On 20/06/2006 12:56 AM, Jason van Zyl wrote:
> Make a plugin to check all these thing and plug it into the validation
> phase. This is all nice to enumerate but it will only take effect when
> it is easy for people to comply.
Yah, sorry, I assumed everyone knew what docck was by osmosis or
something. John Casey wrote it (in the sandbox) not too long ago to do
just that. It needs some more work, but that's one of the items in the list.
Thanks!
- Brett
--
Brett Porter <br...@apache.org>
Apache Maven - http://maven.apache.org/
Better Builds with Maven - http://library.mergere.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Plugin documentation standard
Posted by Jason van Zyl <ja...@maven.org>.
On 19 Jun 06, at 9:47 AM 19 Jun 06, Brett Porter wrote:
> Hi,
>
> Just thought I'd break this one out. This needs to be converted to
> a guide - which is one of the tasks I'll list at the end.
>
> (this is MNG-1987, btw)
>
> * Required POM Elements
>
> - modelVersion, version, group ID, artifact ID, packaging (required
> anyway to build)
> - name
> - description
> - url
> - issueManagement
> - prerequisites > maven (I think it's good to make people think
> about this)
> - inceptionYear
> - mailingLists (just a warning if missing as I guess there might
> not be one, though we should have some other contact details - do
> general contact details fit a "list" description?)
> - license
> - scm (warning if missing, may not be OSS!)
> - organization
> - plugin report must be configured
>
> * Plugin configuration
>
> - each @parameter field must have a description. Not required if
> @readonly or @component
> - Class level should have a description.
>
> * Documents
>
> - plugins must have an /index.html (from apt, xdoc, html etc). Not
> generated automatically
> - plugins must have a /usage.html, where the standard use case is
> described. The recommended lifecycle phases should be listed. This
> will almost be boilerplate (just some common configuration items,
> how to include it in the POM, and whether it usually needs
> executions or not). It will probably repeat for each goal available.
> - plugins should have examples/*.html for individual use cases.
> - plugins should have a FAQ page for common questions, issues, and
> misunderstandings
>
> Consider this example:
> - use case: http://maven.apache.org/plugins/maven-release-plugin/
> introduction.html
> - specific examples: http://maven.apache.org/plugins/maven-release-
> plugin/howto.html (should be broken out into examples/dryRun.apt, etc)
>
> * Site descriptor
>
> - navigation must include the link to the usage and the examples
> under that
>
> * Reports
>
> - Plugin must have javadoc, jxr and changelog reports
>
> * General guidelines
>
> - Always be able to publish the latest and greatest. Mark new
> features with the version they were introduced. Mark caveats in
> certain versions.
> - The Jetty6 and Cargo plugins are the level of information we are
> looking for.
>
> * Tasks (any volunteers? If so, please create a JIRA and grab it
> (and drop a reply here to say so - eventually we'll get these all
> in regardless though)
> - convert the above to a guide on the Maven website
> - add any missing checks to the docck plugin
> - wire up the docck plugin to all maven plugins
> - pilot plugins. Some of these have gone into JIRA already and been
> assigned.
> - rework the plugin reference page (a separate discussion,
> MPLUGIN-7 is a starting point). This should be reworked not to
> overwrite index.html
> - create an archetype for a compliant plugin
> - add @since tag to plugin fields (it's standard javadoc so we can
> dual purpose it, but we need to acknowledge it in the descriptor)
>
> Any additional thoughts?
>
Make a plugin to check all these thing and plug it into the
validation phase. This is all nice to enumerate but it will only take
effect when it is easy for people to comply.
> - Brett
>
>
> --
> Brett Porter <br...@apache.org>
> Apache Maven - http://maven.apache.org/
> Better Builds with Maven - http://library.mergere.com/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Jason van Zyl
jason@maven.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Plugin documentation standard
Posted by Dennis Lundberg <de...@apache.org>.
Brett Porter wrote:
> Hi,
>
> Just thought I'd break this one out. This needs to be converted to a
> guide - which is one of the tasks I'll list at the end.
>
> (this is MNG-1987, btw)
>
> * Required POM Elements
>
> - modelVersion, version, group ID, artifact ID, packaging (required
> anyway to build)
> - name
> - description
> - url
> - issueManagement
> - prerequisites > maven (I think it's good to make people think about this)
> - inceptionYear
> - mailingLists (just a warning if missing as I guess there might not be
> one, though we should have some other contact details - do general
> contact details fit a "list" description?)
> - license
> - scm (warning if missing, may not be OSS!)
> - organization
> - plugin report must be configured
>
> * Plugin configuration
>
> - each @parameter field must have a description. Not required if
> @readonly or @component
> - Class level should have a description.
>
> * Documents
>
> - plugins must have an /index.html (from apt, xdoc, html etc). Not
> generated automatically
> - plugins must have a /usage.html, where the standard use case is
> described. The recommended lifecycle phases should be listed. This will
> almost be boilerplate (just some common configuration items, how to
> include it in the POM, and whether it usually needs executions or not).
> It will probably repeat for each goal available.
> - plugins should have examples/*.html for individual use cases.
> - plugins should have a FAQ page for common questions, issues, and
> misunderstandings
>
> Consider this example:
> - use case:
> http://maven.apache.org/plugins/maven-release-plugin/introduction.html
> - specific examples:
> http://maven.apache.org/plugins/maven-release-plugin/howto.html (should
> be broken out into examples/dryRun.apt, etc)
>
> * Site descriptor
>
> - navigation must include the link to the usage and the examples under that
>
> * Reports
>
> - Plugin must have javadoc, jxr and changelog reports
>
> * General guidelines
>
> - Always be able to publish the latest and greatest. Mark new features
> with the version they were introduced. Mark caveats in certain versions.
> - The Jetty6 and Cargo plugins are the level of information we are
> looking for.
>
> * Tasks (any volunteers? If so, please create a JIRA and grab it (and
> drop a reply here to say so - eventually we'll get these all in
> regardless though)
> - convert the above to a guide on the Maven website
> - add any missing checks to the docck plugin
> - wire up the docck plugin to all maven plugins
> - pilot plugins. Some of these have gone into JIRA already and been
> assigned.
> - rework the plugin reference page (a separate discussion, MPLUGIN-7 is
> a starting point). This should be reworked not to overwrite index.html
> - create an archetype for a compliant plugin
> - add @since tag to plugin fields (it's standard javadoc so we can dual
> purpose it, but we need to acknowledge it in the descriptor)
>
> Any additional thoughts?
One more more thing:
I read somewhere that users find it hard to know if a plugin is for
Maven 1 or Maven 2. So adding a "Maven 2" label somewhere prominent
would be good.
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org