Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Overview</h1>
<p>This guide will walk you through</p>
<ul>
	<li>downloading the latest source code from the trunk of a plugin</li>
	<li>building the plugin</li>
	<li>creating JIRA issues</li>
	<li>modifying the plugin source code</li>
	<li>deploying the plugin to an internal repository for use within your company</li>
	<li>creating patches and attaching to JIRA</li>
	<li>applying patches retrieved from JIRA</li>
</ul>

<h1>Known Issues</h1>

<h2>Single Artifact can not be available on multiple repositories</h2>

<p>See <a class="external-link" href="http://www.nabble.com/forum/ViewPost.jtp?post=7884079&amp;framed=y&amp;skin=177" rel="nofollow">http://www.nabble.com/forum/ViewPost.jtp?post=7884079&amp;framed=y&amp;skin=177</a>, a single artifact can not be available on multiple repositories.  </p>

<p>The workaround is to install mvnproxy and include in the configuration all internal repositories.<br />
This way mvnproxy will aggregate all the configured repositories regardless of what actual repository was requested.  That is, even though an artifact from central was requested, mvnproxy will return any matching files found for all the repositories that are configured within mvnproxy.</p>

<p>The previous workaround was to suffix &quot;-i&quot; to the artifactId, which is a broken workaround as this makes a duplicate copy of the artifact with a different name and will cause two potentially incompatible libraries to be on the classpath.  If you see any references to this workaround in this document please make corrections.</p>

<h2>Long file names on Windows</h2>

<p>Previous versions of this document recommended a naming convention like -INTERNAL-r&lt;svn rev&gt;-p&lt;Patch Num&gt;-p&lt;Patch Num&gt;...  The problem is that this causes very long file names on windows and then when you run maven the java will fail with a general protection fault.  Please ensure you dont use long version values.</p>

<h1>Downloading the latest source code from the trunk of a plugin</h1>

<p>Maven uses <a href="http://subversion.tigris.org">Subversion</a> as it's source control repository. The base subversion repository is located at <a class="external-link" href="http://svn.apache.org/repos/asf/maven" rel="nofollow">http://svn.apache.org/repos/asf/maven</a>. Within this structure there are a number of different directories of useful files:</p>

<ul>
	<li><a class="external-link" href="http://svn.apache.org/repos/asf/maven/plugins/trunk" rel="nofollow">http://svn.apache.org/repos/asf/maven/plugins/trunk</a> - all maven plugins</li>
	<li><a class="external-link" href="http://svn.apache.org/repos/asf/maven/sandbox/plugins" rel="nofollow">http://svn.apache.org/repos/asf/maven/sandbox/plugins</a> - sandboxed maven plugins (ones that have not been promoted into common use)</li>
	<li><a class="external-link" href="http://svn.apache.org/repos/asf/maven/components/trunk" rel="nofollow">http://svn.apache.org/repos/asf/maven/components/trunk</a> - the maven core itself</li>
	<li><a class="external-link" href="http://svn.apache.org/repos/asf/maven/shared/trunk" rel="nofollow">http://svn.apache.org/repos/asf/maven/shared/trunk</a> - shared components (e.g. maven-archiver)</li>
	<li>codehaus plugins - see their respective web pages for their location, the general format is svn.codehaus.org/<em>project</em>/trunk</li>
</ul>

<p>Using your favourite subversion tool, check out the plugin you want (e.g. <a class="external-link" href="http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-assembly-plugin" rel="nofollow">http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-assembly-plugin</a>)</p>

<h1>Building the plugin</h1>

<p>Maven developers try to ensure that the trunk always builds and to build your own copy use <code>mvn package</code>.</p>

<p>However because the plugin may be using snapshot versions of other plugins, you will need to ensure you have setup your environment correctly to obtain any dependencies from the snapshot repositories.  See the <a class="confluence-link" href="/display/MAVEN/Development+Procedures" data-linked-resource-id="58527" data-linked-resource-type="page" data-linked-resource-default-alias="Development Procedures" data-base-url="http://docs.codehaus.org">Maven Development Procedures</a> for more details on how to configure your environment.  You may also want to read <a href="http://maven.apache.org/guides/development/guide-testing-development-plugins.html">Guide to Testing Development Versions of Plugin</a> and <br />
<a href="http://maven.apache.org/guides/development/guide-plugin-snapshot-repositories.html">Guide to Plugin Snapshot Repositories</a> (this guide contains the codehaus snapshot repository setup)</p>

<p>Here are the profiles in use from following the advice above:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
    &lt;profile>
      &lt;id>apache&lt;/id>
      &lt;repositories>
        &lt;repository>
          &lt;id>apache.snapshots&lt;/id>
          &lt;name>Maven Snapshots&lt;/name>
          &lt;url>http://people.apache.org/maven-snapshot-repository&lt;/url>
          &lt;releases>
            &lt;enabled>false&lt;/enabled>
          &lt;/releases>
          &lt;snapshots>
            &lt;enabled>true&lt;/enabled>
          &lt;/snapshots>
        &lt;/repository>
      &lt;/repositories>
      &lt;pluginRepositories>
        &lt;pluginRepository>
          &lt;id>apache.snapshots&lt;/id>
          &lt;name>Maven Plugin Snapshots&lt;/name>
          &lt;url>http://people.apache.org/maven-snapshot-repository&lt;/url>
          &lt;releases>
            &lt;enabled>false&lt;/enabled>
          &lt;/releases>
          &lt;snapshots>
            &lt;enabled>true&lt;/enabled>
          &lt;/snapshots>
        &lt;/pluginRepository>
      &lt;/pluginRepositories>
    &lt;/profile>
    &lt;profile>
      &lt;id>codehaus.org&lt;/id>
      &lt;repositories>
        &lt;repository>
          &lt;id>codehaus.org&lt;/id>
          &lt;name>CodeHaus Snapshots&lt;/name>
          &lt;url>http://snapshots.repository.codehaus.org&lt;/url>
          &lt;releases>
            &lt;enabled>false&lt;/enabled>
          &lt;/releases>
          &lt;snapshots>
            &lt;enabled>true&lt;/enabled>
          &lt;/snapshots>
        &lt;/repository>
      &lt;/repositories>
      &lt;pluginRepositories>
        &lt;pluginRepository>
          &lt;id>codehaus.org&lt;/id>
          &lt;name>CodeHaus Plugin Snapshots&lt;/name>
          &lt;url>http://snapshots.repository.codehaus.org&lt;/url>
          &lt;releases>
            &lt;enabled>false&lt;/enabled>
          &lt;/releases>
          &lt;snapshots>
            &lt;enabled>true&lt;/enabled>
          &lt;/snapshots>
        &lt;/pluginRepository>
      &lt;/pluginRepositories>
    &lt;/profile>
</pre></td></tr></table>

<h1>Creating JIRA issues</h1>

<p>Find the project for the maven plugin at <a class="external-link" href="http://jira.codehaus.org/secure/BrowseProjects.jspa" rel="nofollow">http://jira.codehaus.org/secure/BrowseProjects.jspa</a>.</p>

<p>Before you create a new JIRA issue you should confirm that there is no existing issue already available.<br />
If one already exists, check what other people have suggested for a suitable solution.  If there is a patch already, try using that before making your own modifications.</p>

<h1>Modifying the plugin source code</h1>

<p>The first step should be to create a unit test.</p>

<p>After the unit test has been created modify the code to pass the unit test.</p>

<p>Once the unit test is passing you can then build the plugin and attempt to use it locally via <code>mvn install</code>.  You should check that the plugin works as expected in your project.</p>

<h1>Creating patches and attaching to JIRA</h1>

<p>In the root directory of the plugin you have been modifying use <code>svn diff &gt; ../<em>JIRA COMPONENT</em>-<em>JIRA ID</em>-patch.txt</code> e.g. <code>svn diff &gt; ../MASSEMBLY-118-patch.txt</code>.</p>

<p>Find the JIRA issue you previously created and click the <code>Attach file</code> link on the left side under the <code>Operations</code> links.  In the comment text area provide a brief description of the patch contents and anything of interest that should be pointed out.</p>

<h1>Applying patches retrieved from JIRA</h1>

<p>You will need a <code>patch</code> program.  Unix should come with patch out of the box.  On Windows your choices are to use <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://gnuwin32.sourceforge.net/packages/patch.htm">GNU Patch</a>.</p>

<p>In the root directoy of the plugin run <code>patch -p0 &lt; <em>PATCH FILE</em></code> e.g. <code>patch -p0 &lt; ../MASSEMBLY-118-patch.txt</code>. The <code>-p0</code> says to patch that there are no leading paths that need to be stripped from the patch file.  In general you won't need to modify this, but if you do look at the <br />
patch file for lines like <code>Index: <em>FILE</em></code> and work out how many path elements should be stripped and use that number as the option to <code>-p</code></p>

<h1>Deploying the plugin to an internal repository for use within your company</h1>

<p>If you have an internal repository that is used by your company then you will want to deploy your patched versions to this repository until your patches have been applied to the plugin.  If you don't have an internal repository you should consider setting one up, see <a class="confluence-link" href="/display/MAVENUSER/Using+Maven+in+a+corporate+environment" data-linked-resource-id="43623" data-linked-resource-type="page" data-linked-resource-default-alias="Using Maven in a corporate environment" data-base-url="http://docs.codehaus.org">Using Maven in a corporate environment</a> for more details.</p>

<p>Before you start, ensure that your pom file does not depend upon any <code>SNAPSHOT</code> versions, if it does then for each <code>SNAPSHOT</code> version you will need to checkout the trunk for that artifact, build it and then follow the steps below to promote it to an internal release, otherwise you won't have any control over the build process. </p>

<p>Make the following changes to the <code>pom.xml</code> file after making a backup copy.</p>

<ul>
	<li>Set the version to be <code>-INTERNAL-r&lt;svn version&gt;</code> instead of <code>-SNAPSHOT</code>.  See <a href="http://www.mergere.com/m2book_download.jsp">Better Builds with Maven (June 2006)</a> page 61 for an explanation of how version numbers are compared. e.g. if the version is <code>2.2-SNAPSHOT</code> and the subversion repository when you checked out the plugin was at r485327 then set it to <code>2.2-INTERNAL-r485327</code>. Note: When the plugin is officially released as <code>2.2</code> the released version will be considered newer than your patched version and supercede it. You will need to check if your patches have been applied in the release and if not then follow these instructions again. By including the patch numbers in the version id it will help you identify immediately what needs to get checked.</li>
</ul>

<ul>
	<li>Modify the description to include exactly what revision of the version repository the build is from and also if any patches (include links) that have been applied.  You will need this information later when you try to work out what was in your internal release and when new releases occur what you need to do to back port and get a working internal release again. e.g:
<table class="wysiwyg-macro" data-macro-name="code" data-macro-parameters="language=xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
...
  &lt;description>
    Internal release from subversion revision r485475. 
    No patches applied.
or
    Patches applied:
    * http://jira.codehaus.org/browse/MECLIPSE-206
    * ...
  &lt;/description>
...
</pre></td></tr></table></li>
</ul>

<ul>
	<li>Add a distributionManagement section (or overwrite the existing section). As this is an internal release it will go to your internal_plugins repository, if you forget to do this you will be attempting to release into the maven repositories which you don't have access to.
<table class="wysiwyg-macro" data-macro-name="code" data-macro-parameters="language=xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
  ...
  &lt;distributionManagement>
    &lt;repository>
      &lt;id>internal_plugins&lt;/id>
      &lt;name>Internal Plugin Repository&lt;/name>
      &lt;url>
        scp://NUCLEUS/path/to/maven2_repositories/internal_plugins
      &lt;/url>
    &lt;/repository>
  &lt;/distributionManagement>  
</pre></td></tr></table></li>
</ul>

<ul>
	<li>Include the maven-source-plugin so that the source jars get created as part of deployment, there appears to be no profile available in the parent hierarchy to enable this.
<table class="wysiwyg-macro" data-macro-name="code" data-macro-parameters="language=xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
  &lt;build>
    ...
    &lt;plugins>
      ...
      &lt;plugin>
        &lt;groupId>org.apache.maven.plugins&lt;/groupId>
        &lt;artifactId>maven-source-plugin&lt;/artifactId>
        &lt;executions>
          &lt;execution>
            &lt;goals>
              &lt;goal>jar&lt;/goal>
            &lt;/goals>
          &lt;/execution>
        &lt;/executions>
      &lt;/plugin>
</pre></td></tr></table></li>
</ul>

<ul>
	<li>Remove any snapshot repository definitions.  These are in the <code>repositories</code> section and contain an enabled <code>snapshots</code> section.</li>
</ul>

<p>Any <code>SNAPSHOT</code> dependencies need to be internally released by following the above instructions.  The dependency version is then changed from <code>-SNAPSHOT</code> to <code>-INTERNAL</code>. This can be quite a long process of chasing the dragon's tail.  </p>

<p>You will need to also chase parent definitions that are a <code>SNAPSHOT</code> version. Since you only need the pom definition use <code>mvn -N</code> to avoid recursing into the module directories (which you don't care about and don't need to checkout). Parent poms are located one directory above the current pom, unless there is a <code>relativePath</code> declaration.  </p>

<p>Each dependency and parent pom that is promoted to <code>INTERNAL</code> needs to be deployed to your internal repository via <code>mvn deploy</code>, you must do this depth first so that the pom you are deploying has no <code>SNAPTSHOT</code> dependencies.</p>

<p>Once all dependencies and parents have been deployed you can now deploy your changes to the plugin to your internal repository via <code>mvn deploy</code>.</p>