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