[jira] Commented: (MNG-142) project usage instructions in POM

[ji...@codehaus.org]

The following comment has been added to this issue:

     Author: Michal Maczka
    Created: Mon, 14 Feb 2005 3:49 AM
       Body:
Aren't we planning to make it that simple that such docs won't be simply needed?

build, install, deploy can replace respectivly

- jar,jar:jar, war,ear, ...
- jar:install,war:intall, ...
- jar:deploy, war:deploy, ...



This means that if you know 3-4 goal names you can build any project, deploy/install main artifact to repository.
---------------------------------------------------------------------
View this comment:
  http://jira.codehaus.org/browse/MNG-142?page=comments#action_29840

---------------------------------------------------------------------
View the issue:
  http://jira.codehaus.org/browse/MNG-142

Here is an overview of the issue:
---------------------------------------------------------------------
        Key: MNG-142
    Summary: project usage instructions in POM
       Type: New Feature

     Status: Unassigned
   Priority: Minor

 Original Estimate: Unknown
 Time Spent: Unknown
  Remaining: Unknown

    Project: m2
 Components: 
             maven-model

   Assignee: 
   Reporter: Brett Porter

    Created: Sun, 13 Feb 2005 6:49 PM
    Updated: Mon, 14 Feb 2005 3:49 AM

Description:
I was wondering if we could wing in a new feature to m2, which is a short set of build instructions for projects to show the user with maven -u. In m1, this is done by showing pom.description + any maven.xml goals, which is very crude.

What I was thinking for m2 was the following:
- maven -u shows maven.xml goals plus goals relevant to artifact type (jar:* for jar, war:* for war - a new piece of metadata to indicate that attribute should be show in the usage would be useful)
- a new element <usage/> to the POM. This should reference an apt filename (a default of src/site/apt/usage.apt can be used), which is just displayed verbatim before the goal references.

This means even someone new to Maven can pick up someone else's project, run maven -u and get all the standard information, plus anything the project author wants to add (prerequesites, custom defined goals, etc.)

Another addition might be to add extra goal descriptions to the output so they can recommend some to the user on some occasions, but not on others.

This would override the default goals that are shown, so a more complete element might be:
<usage>
  <!-- Plain text description to show instead of loading from a file - only one should be used -->
  <description>
    To build the jar for this project, simply run
    "maven jar".
  </description>
  <!-- External APT description to show verbatim -->
  <file>docs/apt/usage.apt</file>
  <!-- Optional - defaults to those relevant to the artifact type -->
  <recommended-goals>jar, install, deploy, site</recommended-goals>
</usage>




---------------------------------------------------------------------
JIRA INFORMATION:
This message is automatically generated by JIRA.

If you think it was sent incorrectly contact one of the administrators:
   http://jira.codehaus.org/secure/Administrators.jspa

If you want more information on JIRA, or have a bug to report see:
   http://www.atlassian.com/software/jira