<?xml version="1.0"?>

<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->

<document>
<!-- TODO: include back into site, after checking which are complete, add to instructions on how to contribute docs -->
  <properties>
    <title>Documentation Required</title>
    <author email="brett@apache.org">Brett Porter</author>
  </properties>
  <body>
    <section name="Documentation Required">
      <p>
        This page lists some of the most pressing documentation needs. If you feel something is missing, please be sure
        to let us know at the
        <a href="/mail-lists.html">Maven Users Mailing List</a>.
      </p>
      <h4>Documentation for users</h4>
      <ul>
        <li>new SNAPSHOT handling -
          <i>partially done on Brett's blog</i>
        </li>
        <li>guide to dependencies, including:
          <ul>
            <li>dependency scoping - <i>especially system scope</i></li>
            <li>version range specifications</li>
            <li>conflict resolution</li>
          </ul>
        </li>
        <li>deployment mechanism</li>
        <li>dependency management</li>
        <li>plugin management -
          <i>in progress by J Matthew Pryor and John Casey</i>
        </li>
        <li>plugin configuration</li>
        <li>plugin downloading -
          <i>partial on Brett's blogs</i>
        </li>
        <li>report generation</li>
        <li>project inheritence and company wide strategy</li>
        <li>plugin documentation</li>
        <li>using POM-properties in conjunction with plugin configuration to abstract child-POM configs</li>
        <li>archetypes - writing and using</li>
        <li>plugin usage guide/summary for core plugins - <i>esp. release plugin</i></li>
        <li>strategy for migrating from Ant builds</li>
        <li>strategy for migrating from Maven 1.x builds - <i>esp. plugins that don't convert directly</i></li>
      </ul>
      <h4>Documentation for plugin authors</h4>
      <ul>
        <li>Beanshell examples</li>
        <li>plugin writing guide</li>
        <li>report writing guide</li>
        <li>site customisation guide</li>
        <li>common tips and tricks for accessing project/build data</li>
        <li>guide to available parameter expressions</li>
        <li>list of standards for submitting new plugins (minimum documentation, test coverage?)</li>
      </ul>
      <h4>Documentation for Maven developers</h4>
      <ul>
        <li>Lifecycle architecture</li>
        <li>High level architecture, components explanation</li>
        <li>Intro to Plexus</li>
        <li>contributors guide (add to current and consolidate, walk through some first steps)</li>
      </ul>
      <h4>Additional Notes</h4>
      <pre>
        Brett Porter wrote:
        > The active project changes during the reactor build. At the compile
        > stage, it refers to the target/classes directory. At the package
        > stage, it points to the jar file. If you are implementing your own
        > packaging goal, you need to call project.getArtifact().setFile( ... )
        > to ensure this is used.

        - multi module howto
        - per user scm setup
          - outline behaviour when connection and developConnection are defined

           Our current URL looks like:
           scm:cvs:pserver:@cvs.host.name:/cvsroot:module-version

           Using this URL, the default is to connect to the CVS server using the
           same userid as the current user.  This is the desired behavior and I
           don't want to mess that up.  I just would like a means to add a userid
           in the URL only in special circumstances like Continuum.

           We might want to do something where we say it is a best practice to
           specify a ${user} and take it from the environment and allow an override.

        - testing a plugin
        - How to get started behind an NTLM proxy.
        - How snapshots works
        - How do i use the lifecycle provided by a plugin:
        - How do i disable ibiblio
        - using version ranges
        - plugin expressions (look at bob allison's work)
        - overriding the central repository (use central)
        - description of what packagings are available and how they work
        - creating upload bundles
        - modello example
        - changing the snapshot policy frequency
        - overriding central repo
        - using POM info in applications: the POM is packaged so there is acccess
          continuum example to get the version.
        - quick description of scm,wagon,continuum        
      </pre>
      <h4>Profiles Example</h4>
      <pre><![CDATA[
it's possible to do it with m2 beta-1 and profiles.

you declare profile in your pom like this:

   <profiles>
     <profile>
       <id>env-test</id>
       <activation>
         <property>
           <name>env</name>
           <value>test</value>
         </property>
       </activation>
       <properties>
         <appProperties>test.properties</appProperties>
       </properties>
     </profile>
     <profile>
       <id>env-production</id>
       <activation>
         <property>
           <name>env</name>
           <value>production</value>
         </property>
       </activation>
       <properties>
         <appProperties>app.properties</appProperties>
       </properties>
     </profile>
   </profiles>

and you can run mvn with one of profiles like:
mvn -P env-production clean:clean install ==> we use the profile id
or
mvn -Denv=test clean:clean install ==> we use the property env define in
<activation>

Emmanuel

martin.kuhn@merkur.at wrote:
> Hi,
>
> I'm a maven newbie and I try out maven 2.0 alpha 3.
>
> My questions:
>
> I have a project to build / deploy for three different enviroments (test,
> integration, production).
>
> The difference beetween the bundles is only a properties file (there are
> three different files: config-test.properties,
> config-integration.properties ...).
> In the build process I want to copy the right config file to a file with a
> common name (config.properties -> the app should work with this config
> file)
>
> Is there a solution to handle this with maven 2 or do I have to write a
> plugin?
>
        ]]>
      </pre>
    </section>
  </body>
</document>


