Modified: maven/website/content/general.html ============================================================================== --- maven/website/content/general.html (original) +++ maven/website/content/general.html Sun May 12 07:42:36 2024 @@ -2,15 +2,15 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/fml/general.fml at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/fml/general.fml at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> - <title>Maven</title> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> + <title>Maven â Frequently Asked Technical Questions</title> <link rel="stylesheet" href="./css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="./css/site.css" /> <link rel="stylesheet" href="./css/print.css" media="print" /> @@ -37,10 +37,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="./" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="./" id="bannerRight"><img src="images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -48,9 +46,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/fml/general.fml";><img src="./images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Frequently Asked Technical Questions <a href="https://github.com/apache/maven-site/tree/master/content/fml/general.fml";><img src="./images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="download.cgi" title="Download">Download</a></li> @@ -146,7 +143,7 @@ <main id="bodyColumn" class="span10" > <section><a id="top"></a> <h1>Frequently Asked Technical Questions</h1> -<ol style="list-style-type: decimal;"> +<ol style="list-style-type: decimal"> <li><a href="#encoding-warning">How do I prevent "[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!"</a></li> <li><a href="#scope-provided">How do I prevent including JARs in WEB-INF/lib? I need a "compile only" scope!</a></li> <li><a href="#available-plugins">How do I list available plugins?</a></li> @@ -181,13 +178,13 @@ your POM (or one of its parent POMs): </p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> ... -</project></code></pre> +</project></pre></div> <p style="text-align: right;"><a href="#top">[top]</a></p><hr /></dd><a id="scope-provided"></a> <dt>How do I prevent including JARs in WEB-INF/lib? I need a "compile only" scope!</dt> @@ -269,21 +266,21 @@ target JVM to 7, you should have in your pom: </p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <properties> <maven.compiler.source>1.7</maven.compiler.source> <maven.compiler.target>1.7</maven.compiler.target> </properties> ... -</project></code></pre> +</project></pre></div> <p> Or if a parent pom overrides for compiler plugin default values and you can't fix it, you'll have to explicitly force the values in the compiler plugin configuration: </p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <build> ... @@ -301,7 +298,7 @@ ... </build> ... -</project></code></pre> +</project></pre></div> <p style="text-align: right;"><a href="#top">[top]</a></p><hr /></dd><a id="dir-struct"></a> <dt>Is it possible to create my own directory structure?</dt> @@ -359,7 +356,7 @@ </p> -<pre><code> +<div class="verbatim source"><pre class="prettyprint linenums"> mvn install:install-file -Dfile=<path-to-file> -DgroupId=<group-id> @@ -373,7 +370,7 @@ Where: <path-to-file> the path to <artifact-id> the artifact name for the file <version> the version of the file <packaging> the packaging of the file e.g. jar - </code></pre> + </pre></div> <p> This should load in the file into the Maven repository, renaming it as needed. @@ -428,16 +425,16 @@ Where: <path-to-file> the path to <p>Configure the reporting output encoding in your pom </p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <properties> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> </properties> ... -</project></code></pre> +</project></pre></div> or if default encoding is overridden in a parent pom that you can't change, configure the site plugin explicitly: -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <plugin> <groupId>org.apache.maven.plugins</groupId> @@ -448,7 +445,7 @@ Where: <path-to-file> the path to </configuration> </plugin> ... -<project></code></pre> +<project></pre></div> <p> @@ -469,7 +466,7 @@ Where: <path-to-file> the path to Check your settings.xml and pom.xml for a property named "test" which would like this: </p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <properties> <property> @@ -478,19 +475,19 @@ Where: <path-to-file> the path to </property> </properties> ... -</project></code></pre> +</project></pre></div> <p> or </p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <properties> <test>some-value</test> </properties> ... -</project></code></pre> +</project></pre></div> <p style="text-align: right;"><a href="#top">[top]</a></p><hr /></dd><a id="snapshot-artifacts"></a> <dt>Where are Maven SNAPSHOT artifacts?</dt> @@ -521,22 +518,22 @@ Where: <path-to-file> the path to Your favorite IDE probably supports XSD schema's for pom.xml and settings.xml editing. You need to specify the following: </p> -<pre><code> +<div class="verbatim source"><pre class="prettyprint linenums"> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> ... -</project></code></pre> +</project></pre></div> -<pre><code> +<div class="verbatim source"><pre class="prettyprint linenums"> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... -</settings></code></pre> +</settings></pre></div> <p style="text-align: right;"><a href="#top">[top]</a></p><hr /></dd><a id="getting-help"></a>
Modified: maven/website/content/glossary.html ============================================================================== --- maven/website/content/glossary.html (original) +++ maven/website/content/glossary.html Sun May 12 07:42:36 2024 @@ -2,15 +2,15 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/markdown/glossary.md at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/markdown/glossary.md at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> - <title>Maven</title> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> + <title>Maven â Glossary</title> <link rel="stylesheet" href="./css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="./css/site.css" /> <link rel="stylesheet" href="./css/print.css" media="print" /> @@ -37,10 +37,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="./" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="./" id="bannerRight"><img src="images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -48,9 +46,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/markdown/glossary.md";><img src="./images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Glossary <a href="https://github.com/apache/maven-site/tree/master/content/markdown/glossary.md";><img src="./images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="download.cgi" title="Download">Download</a></li> @@ -129,7 +126,99 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section> +<section><section> +<h2>Glossary</h2><!-- +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. +--> + +<p>This document describes some of the most common terms encountered while +using Maven. These terms, that have an explicit meaning for Maven, can +sometimes be confusing for newcomers.</p> +<ul> + +<li> +<p><strong>Project</strong>: Maven thinks in terms of projects. Everything that you +will build are projects. Those projects follow a well defined +“Project Object Model”. Projects can depend on other projects, in +which case the latter are called “dependencies”. A project may +consist of several subprojects, however these subprojects are +still treated equally as projects.</p></li> +<li> +<p><strong>Project Object Model (POM)</strong>: The Project Object Model, almost +always referred as the POM for brevity, is the metadata that Maven +needs to work with your project. Its name is “project.xml” and it is +located in the root directory of each project.</p></li> +<li> +<p><strong>Artifact</strong>: An artifact is something that is either produced or +used by a project. Examples of artifacts produced by Maven for a +project include: JARs, source and binary distributions, WARs. Each +artifact is identified by a <a href="#GroupId">group id</a>, an +artifact ID, a version, an extension and a classifier +(extension+classifier may be named by a <a href="/ref/current/maven-core/artifact-handlers.html">type</a>).</p></li> +<li> +<p><strong>GroupId</strong>: A group ID is a universally unique identifier for a +project. While this is often just the project name (eg. +<code>commons-collections</code>), it is helpful to use a fully-qualified +package name to distinguish it from other projects with a similar +name (eg. <code>org.apache.maven</code>).</p></li> +<li> +<p><strong>Dependency</strong>: A typical Java project relies on libraries to build +and/or run. Those are called “dependencies” inside Maven. Those +dependencies are usually other projects' JAR artifacts, but are +referenced by the POM that describes them.</p></li> +<li> +<p><strong>Plug-in</strong>: Maven is organized in plugins. Every piece of +functionality in Maven is provided by a plugin. Plugins provide +goals and use the metadata found in the POM to perform their task. +Examples of plugins are: jar, eclipse, war. Plugins are primarily +written in Java, but Maven also supports writing plug-ins in +Beanshell and Ant Scripting.</p></li> +<li> +<p><strong>Mojo</strong>: A plugin written in Java consists of one or more mojos. A +mojo is a Java class that implements the +org.apache.maven.plugin.Mojo interface. This means that a mojo is +the implementation for a <strong>goal</strong> in a plugin.</p></li> +<li> +<p><strong>Repository</strong>:</p> +<p>Refer to <a href="./guides/introduction/introduction-to-repositories.html">Introduction to +Repositories</a></p></li> +<li> +<p><strong>Snapshots</strong>: Projects can (and should) have a special version +including <code>SNAPSHOT</code> to indicate that they are a “work in progress”, +and are not yet released. When a snapshot dependency is encountered, +it is always looked for in all remote repositories, and downloaded +again if newer than the local copy.</p> +<p>The version can either be the string <code>SNAPSHOT</code> itself, indicating +“the very latest” development version, or something like +<code>1.1-SNAPSHOT</code>, indicating development that will be released as 1.1 +(i.e. newer than 1.0, but not yet 1.1).</p></li> +<li> +<p><strong>APT</strong>: APT is a wiki-like format of documentation that Maven +currently understands.</p> +<p>For information on how to create APT files, refer to the <a href="./guides/mini/guide-site.html">Guide to +creating a site</a> document.</p></li> +<li> +<p><strong>XDoc</strong>: XDoc is the format of documentation that Maven currently +understands. It is quite simple, and allows embedding XHTML within a +simple layout that is transformed into a uniform site.</p> +<p>For information on how to create XDoc files, refer to the <a href="./guides/mini/guide-site.html">Guide to +creating a site</a> document.</p></li> +</ul></section></section> </main> </div> </div> Modified: maven/website/content/guides/development/guide-building-maven.html ============================================================================== --- maven/website/content/guides/development/guide-building-maven.html (original) +++ maven/website/content/guides/development/guide-building-maven.html Sun May 12 07:42:36 2024 @@ -2,18 +2,18 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/development/guide-building-maven.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/development/guide-building-maven.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Brett Porter" /> <meta name="author" content="Jason van Zyl" /> <meta name="date" content="2015-01-04" /> - <title>Maven</title> + <title>Maven â Guide to Building Maven</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -40,10 +40,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -51,9 +49,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-building-maven.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Guide to Building Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-building-maven.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -148,32 +145,37 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Building_Maven"></a> -<h1>Building Maven</h1><section><a id="Why_would_I_want_to_build_Maven.3F"></a> +<section> +<h1>Building Maven</h1><section> <h2>Why would I want to build Maven?</h2> <p>Building Maven (or a plugin, or any component) yourself is for one of two reasons:</p> <ul> <li>to try out a bleeding edge feature or bugfix (issues can be found in <a href="/issue-management.html"> JIRA</a>),</li> -<li>to fix a problem you are having and submit a patch to the developers team.</li></ul></section><section><a id="Checking_out_the_sources"></a> +<li>to fix a problem you are having and submit a patch to the developers team.</li></ul></section><section> <h2>Checking out the sources</h2> -<p>All of the source code for Maven and its related libraries is in managed in the ASF source code repositories: for details, see <a href="/scm.html">https://maven.apache.org/scm.html</a>.</p></section><section><a id="Building_Maven_1"></a> -<h2>Building Maven</h2><section><a id="Building_a_Maven_Plugin_or_Component"></a> +<p>All of the source code for Maven and its related libraries is in managed in the ASF source code repositories: for details, see <a href="/scm.html">https://maven.apache.org/scm.html</a>.</p></section><section> +<h2>Building Maven</h2><section> <h3>Building a Maven Plugin or Component</h3> <p>Building a Maven plugin or component is like any Maven build:</p> -<pre>mvn install</pre><section><a id="Running_Integration_Tests"></a> +<div class="verbatim"> +<pre>mvn install</pre></div><section> <h4>Running Integration Tests</h4> <p>Before submitting a patch, it is advised to run the integration tests, which are available in the <code>run-its</code> profile:</p> -<pre>mvn -Prun-its install</pre></section></section><section><a id="Building_Maven_core"></a> +<div class="verbatim"> +<pre>mvn -Prun-its install</pre></div></section></section><section> <h3>Building Maven core</h3> <p>Until Maven 3.3, Maven core build could be boostrapped with an Ant build. This bootstrap has been removed in Maven 3.5: you need a pre-built Maven to build Maven from source.</p> <p>To do this, run from the source directory:</p> -<pre>mvn install</pre> +<div class="verbatim"> +<pre>mvn install</pre></div> <p>The assemblies will be created in <code>apache-maven</code>, and can be manually unzipped to the location where you'd like the resulting Maven installed.</p> <p>If you want to have the resulting Maven directly copied to a directory, you can use the <code>distributionTargetDir</code> property:</p> -<pre>mvn -DdistributionTargetDir="$HOME/app/maven/apache-maven-SNAPSHOT" install</pre><section><a id="Running_the_full_Maven_core_integration_tests"></a> +<div class="verbatim"> +<pre>mvn -DdistributionTargetDir="$HOME/app/maven/apache-maven-SNAPSHOT" install</pre></div><section> <h4>Running the full Maven core integration tests</h4> <p>Before checking in a change or submitting a patch to Maven core, it is required to run the core integration tests. Using your local build of Maven, run:</p> -<pre>mvn test -Prun-its</pre> +<div class="verbatim"> +<pre>mvn test -Prun-its</pre></div> <p>Consult <a href="/core-its/">Core ITs documentation</a> for more options.</p></section></section></section></section> </main> </div> Modified: maven/website/content/guides/development/guide-committer-school.html ============================================================================== --- maven/website/content/guides/development/guide-committer-school.html (original) +++ maven/website/content/guides/development/guide-committer-school.html Sun May 12 07:42:36 2024 @@ -2,19 +2,19 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/development/guide-committer-school.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/development/guide-committer-school.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Stephen Connolly" /> <meta name="author" content="Robert Scholte" /> <meta name="date" content="2012-07-11 2017-07-21" /> - <title>Maven</title> + <title>Maven â Do you want to become a Maven Committer?</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -41,10 +41,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -52,9 +50,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-committer-school.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Do you want to become a Maven Committer? <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-committer-school.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -149,22 +146,24 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Do_you_want_to_become_a_Maven_Committer.3F"></a> +<section> <h1>Do you want to become a Maven Committer?</h1> <p>The Apache Software Foundation is a meritocracy. By this we mean that you gain status based on the merit of your work and actions. In fact the status that you gain is a recognition of the merit of your work and actions.</p> <p>Maven is an Apache project, that means that we have to follow the Apache rules and way. One of those rules is that we cannot hand out commit access to anyone who asks for it.</p> <p>To gain commit access you must establish your merit by submitting patches that get picked up by existing committers.</p> <p>After you have contributed enough patches to establish merit, the project management committee decides whether you can be trusted with commit access.</p> -<p><i>The reality is that "It is what it is"TL;DR To become a Maven committer write good patches and get them applied.</i></p></section><section><a id="What_makes_a_good_patch.3F"></a> +<p><i>The reality is that "It is what it is"TL;DR To become a Maven committer write good patches and get them applied.</i></p></section><section> <h1>What makes a good patch?</h1> <p>A good patch is a patch that applies cleanly and includes tests that cover both the positive and negative case and has documentation where relevant.</p> <p>For example, if you were implementing a patch to fix <a class="externalLink" href="http://issues.apache.org/jira/browse/MNG-4612";>MNG-4612</a> you would first need to write a test case that is failing when trying to encrypt</p> -<pre>{DESede}y+qq...==</pre> +<div class="verbatim"> +<pre>{DESede}y+qq...==</pre></div> <p>and a second test case that is passing when trying to encrypt</p> -<pre>password</pre> +<div class="verbatim"> +<pre>password</pre></div> <p>This is in order to be sure that you have written an effective test case that can pass for good data. Then you implement the fix and all the tests should pass. You then take a Subversion compatible† diff of the source code and attach that to the issue in question.</p> <p>To understand how your patch gets evaluated, here is how I apply patches:</p> -<ol style="list-style-type: decimal;"> +<ol style="list-style-type: decimal"> <li>I look at the actual diff, if there is a whole lot of formatting changes irrelevant to the issue being fixed => <b>Patch is no good, ask on JIRA for a clean patch</b></li> <li>I look at the list of files in the diff, if there are no tests => <b>Patch is no good, ask on JIRA for test cases</b></li> <li>I look at the issue and if the issue requires documentation be updated and there is no documentation changes in the patch => <b>Patch is no good, ask on JIRA for documentation changes in the patch</b></li> @@ -172,39 +171,42 @@ <li>I revert the src/main and run the tests. If the tests all pass, then there are no test cases to catch the bug => <b>Patch is no good, ask on JIRA for proper tests</b></li> <li>I revert src and run the tests. If any tests fail, then there is something wrong with the existing code => <b>If I have time I might try and fix the issue, otherwise I just move on</b></li> <li>I apply the patch a second time and run the tests. If the tests all pass => <b>Patch is good, I commit the patch and mark the JIRA as resolved</b></li></ol> -<p>So there you have it, my guide to writing good patches... now the next step is getting your patches noticed...</p></section><section><a id="How_to_get_your_patches_noticed"></a> +<p>So there you have it, my guide to writing good patches... now the next step is getting your patches noticed...</p></section><section> <h1>How to get your patches noticed</h1> <p>The simplest way to get your patches noticed is to submit them to the JIRA issue that they fix.</p> <p>Remember that the Maven project is run by volunteers in their spare time, so very often we may not notice your patch for a few days. </p> <p>If you are certain that your patch is a good patch, and a week has passed with no comments on JIRA, then you should send <i>one and only one</i> email to the <a class="externalLink" href="mailto:d...@maven.apache.org";>d...@maven.apache.org</a> mailing list to see if your patch can get noticed.</p> -<p><b>Note:</b> you need to be fairly confident that your patch is a good patch, because if you keep on pestering the Maven developers looking to have non-good patches applied, your merit will become negative and people will be less inclined to help you get your patches applied... also this is why you should send one and <i>only one</i> email about your patch on any specific JIRA issue.</p></section><section><a id="Stephen.2C_Arnaud_.26_Barrie.27s_school_for_potential_Maven_committers"></a> +<p><b>Note:</b> you need to be fairly confident that your patch is a good patch, because if you keep on pestering the Maven developers looking to have non-good patches applied, your merit will become negative and people will be less inclined to help you get your patches applied... also this is why you should send one and <i>only one</i> email about your patch on any specific JIRA issue.</p></section><section> <h1>Stephen, Arnaud & Barrie's school for potential Maven committers</h1> <p>To help people who are interested in becoming Maven committers fulfill their goals, myself, Arnaud Heritier and Barrie Treloar (along with any other current Maven committers who decide to help) will be running an assignment based class to help people become committers. </p> <p>To register for the class you need to complete the following steps:</p> -<ol style="list-style-type: decimal;"> +<ol style="list-style-type: decimal"> <li>Read the <a class="externalLink" href="http://www.apache.org/licenses/icla.txt";>Apache Individual Contributor License Agreement</a>. When you graduate from the class you will be required to sign this in order to become a committer.</li> <li>Subscribe to the <a class="externalLink" href="mailto:d...@maven.apache.org";>d...@maven.apache.org</a> mailing list.</li> <li>Send an email to the list with the Subject line: <code>[Committer School] I would like to become a committer</code> and the Message body: +<div class="verbatim"> <pre>I am interested in the following areas: _______, _______ and ______ If anyone knows any issues that I could take a look at I would be very much appreciated -Thanks</pre></li></ol> +Thanks</pre></div></li></ol> <p>Once you have registered your class assignments are basically to find JIRA issues that you want to fix. The issues can be in any part of Maven, but it is best to start with the areas you have the most interest in. Once you have found a JIRA issue that you are interested in fixing, the process will work a little something like this:</p> -<ol style="list-style-type: decimal;"> +<ol style="list-style-type: decimal"> <li>Make sure that nobody else is working on the issue and that the issue is one that should be fixed by sending an email to the list with a Subject line something like: <code>[Committer School] Should I fix MNG-4612?</code> The Message body should be something like: +<div class="verbatim"> <pre>I have had a look at MNG-4612 and I think this is a real issue because... I think I can fix it like so.... Is that the correct way to go about fixing it and is it a real issue at all -Thanks</pre></li> +Thanks</pre></div></li> <li>Wait a couple of days. Arnaud, Barrie and I will do our best to respond quickly to all such emails, but please keep in mind that we are doing this in our spare time.</li> <li>If you get the all clear, develop your patch and upload it to the JIRA, after it is uploaded, send an email to the list with a subject line something like: <code>[Committer School] Patch for review: MNG-4612</code> The Message body should be something like: +<div class="verbatim"> <pre>I have tested that this is a good patch and I would appreciate if a committer could review and apply -Thanks</pre></li></ol> +Thanks</pre></div></li></ol> <p>Keep in mind that the Committer School is just a way for us to identify people who are committed to developing patches with a view to eventually becoming committers. </p> <p>When we have enough evidence that we think we can get you accepted as a committer we will nominate you and hopefully your nomination will be accepted.</p> <p>Personally, if I see somebody averaging a good patch a week for 2-3 months and being active helping out on the <a class="externalLink" href="mailto:us...@maven.apache.org";>us...@maven.apache.org</a> and <a class="externalLink" href="mailto:d...@maven.apache.org";>d...@maven.apache.org</a> mailing lists then I think I could make a strong case for such a person being given commit access.</p> Modified: maven/website/content/guides/development/guide-documentation-style.html ============================================================================== --- maven/website/content/guides/development/guide-documentation-style.html (original) +++ maven/website/content/guides/development/guide-documentation-style.html Sun May 12 07:42:36 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/development/guide-documentation-style.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/development/guide-documentation-style.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Dennis Lundberg" /> <meta name="date" content="2008-07-12" /> - <title>Maven</title> + <title>Maven â Guide To Maven Documentation Style</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -39,10 +39,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -50,9 +48,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-documentation-style.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Guide To Maven Documentation Style <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-documentation-style.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -131,36 +128,37 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Guide_To_Maven_Documentation_Style"></a> -<h1>Guide To Maven Documentation Style</h1><section><a id="Where_did_the_style_came_from.3F"></a> +<section> +<h1>Guide To Maven Documentation Style</h1><section> <h2>Where did the style came from?</h2> <p>The documentation style guide was created to make our documentation more consistent and also to apply best practices to the documentation as well. The standard has just been started and will expand over time based on the suggestions made on the Maven dev mailing list. It is a community consensus of how we should write our documentation.</p> -<p>Each rule in this guide should come with a motivation as to why it exists. References to external sources are encouraged.</p></section><section><a id="Date_format"></a> +<p>Each rule in this guide should come with a motivation as to why it exists. References to external sources are encouraged.</p></section><section> <h2>Date format</h2> <p>How people format a date varies around the world, sometimes making it hard for people to understand each other. The solution to this problem comes in the form of the ISO-8601 standard.</p> <p>A date in our documentation must follow this standard:</p> <p><b>YYYY-MM-DD</b></p> <p>where <b>YYYY</b> is the year in the Gregorian calendar, <b>MM</b> is the month of the year between 01 (January) and 12 (December), and <b>DD</b> is the day of the month between 01 and 31.</p> <p><b>Note</b>: All documentation meta-data should respect this convention, for instance for this given APT document:</p> +<div class="verbatim"> <pre> ------ Guide To Maven Documentation Style ------ Dennis Lundberg ------ 2008-07-03 - ------</pre><section><a id="References"></a> + ------</pre></div><section> <h3>References</h3> <ul> <li><a class="externalLink" href="http://www.w3.org/QA/Tips/iso-date";>W3C Quality Web Tips</a></li> <li><a class="externalLink" href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26780";>ISO-8601</a></li> -<li><a class="externalLink" href="http://en.wikipedia.org/wiki/ISO_8601";>Wikipedia</a></li></ul></section></section><section><a id="POM_Snippet"></a> +<li><a class="externalLink" href="http://en.wikipedia.org/wiki/ISO_8601";>Wikipedia</a></li></ul></section></section><section> <h2>POM Snippet</h2> <p>A POM file must use 2 spaces for each indentation. Because POM snippets are often used in documentation to show the user how to configure something, it is important that these snippets aren't too wide. If they are too wide, the page is difficult to read on a smaller screen.</p> <p>When you use a snippet of XML from the POM as an example in documentation, make sure that the example is properly indented. A user should be able to copy and paste the example into their own POM without changing the indentation.</p> -<p>Also, you should declare all parent POM elements to improve the comprehension. You could use ellipsis (i.e. ...) if you don't want to specify elements.</p><section><a id="Example"></a> +<p>Also, you should declare all parent POM elements to improve the comprehension. You could use ellipsis (i.e. ...) if you don't want to specify elements.</p><section> <h3>Example</h3> <p>The following is an example of how the distribution management of the Maven site is configured.</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <distributionManagement> <site> @@ -169,13 +167,14 @@ </site> </distributionManagement> ... -</project></code></pre> -<p>As you can see above the <code><distributionManagement></code> element is indented once (=2 spaces), the <code><site></code> element is indented twice (=4 spaces), and the <code><id></code> is indented three times (=6 spaces).</p></section></section><section><a id="Naming_Documentation_Files"></a> +</project></pre></div> +<p>As you can see above the <code><distributionManagement></code> element is indented once (=2 spaces), the <code><site></code> element is indented twice (=4 spaces), and the <code><id></code> is indented three times (=6 spaces).</p></section></section><section> <h2>Naming Documentation Files</h2> <p>All file names should replace space by a hyphen (-), for instance for this given APT document:</p> -<pre> guide-documentation-style.apt</pre></section><section><a id="Updating_Documentation_Files"></a> +<div class="verbatim"> +<pre> guide-documentation-style.apt</pre></div></section><section> <h2>Updating Documentation Files</h2> -<p>A good practice is to update the date (with the correct date format) when you are updating documentation files.</p></section><section><a id="Write_Thinking"></a> +<p>A good practice is to update the date (with the correct date format) when you are updating documentation files.</p></section><section> <h2>Write Thinking</h2> <p>Here are some pointers about English rules when typing material:</p> <ul> Modified: maven/website/content/guides/development/guide-helping.html ============================================================================== --- maven/website/content/guides/development/guide-helping.html (original) +++ maven/website/content/guides/development/guide-helping.html Sun May 12 07:42:36 2024 @@ -2,19 +2,19 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/development/guide-helping.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/development/guide-helping.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Brett Porter" /> <meta name="author" content="Jason van Zyl" /> <meta name="date" content="2008-07-03 2015-06-16" /> - <title>Maven</title> + <title>Maven â Guide to helping with Maven</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -41,10 +41,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -52,9 +50,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-helping.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Guide to helping with Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-helping.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -143,7 +140,7 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Guide_to_helping_with_Maven"></a> +<section> <h1>Guide to helping with Maven</h1> <p>As with any open source project, there are several ways you can help:</p> <ul> @@ -154,17 +151,17 @@ <li><a href="./guide-testing-releases.html"> Test releases</a> help test releases that are being voted on (see the <a href="../../mailing-lists.html">d...@maven.apache.org list</a> for release votes)</li> <li><a href="./guide-testing-development-plugins.html"> Test snapshot plugins</a> help test the latest development versions of plugins and report issues</li> <li>Help with the documentation by pointing out areas that are lacking or unclear, and if you can, submitting Pull Requests to correct it: use the "edit" button in the breadcrumb, just after the page title. You can also create appropriate issues <a class="externalLink" href="https://issues.apache.org/jira/browse/MNGSITE";>by using the issue management system</a>.</li></ul> -<p>Your participation in the community is much appreciated!</p></section><section><a id="Why_Would_I_Want_to_Help.3F"></a> +<p>Your participation in the community is much appreciated!</p></section><section> <h1>Why Would I Want to Help?</h1> <p>There are several reasons these are good things.</p> <ul> <li>By answering other people's questions, you can learn more for yourself</li> <li>By submitting your own fixes, they get incorporated faster</li> <li>By reporting issues, you ensure that bugs don't get missed, or forgotten</li> -<li>You are giving back to a community that has given you software for free</li></ul></section><section><a id="How_do_I_Join_the_Project.3F"></a> +<li>You are giving back to a community that has given you software for free</li></ul></section><section> <h1>How do I Join the Project?</h1> <p>Projects at Apache operate under a meritocracy, meaning those that the developers notice participating to a high extent will be invited to join the project as a committer.</p> -<p>This is as much based on personality and ability to work with other developers and the community as it is with proven technical ability. Being unhelpful to other users, or obviously looking to become a committer for bragging rights and nothing else is frowned upon, as is asking to be made a committer without having contributed sufficiently to be invited.</p></section><section><a id="Developers_Conventions"></a> +<p>This is as much based on personality and ability to work with other developers and the community as it is with proven technical ability. Being unhelpful to other users, or obviously looking to become a committer for bragging rights and nothing else is frowned upon, as is asking to be made a committer without having contributed sufficiently to be invited.</p></section><section> <h1>Developers Conventions</h1> <p>There are a number of conventions used in the project, which contributors and developers alike should follow for consistency's sake.</p> <ul> @@ -172,7 +169,7 @@ <li><a href="../../developers/conventions/jira.html">Maven Jira Convention</a></li> <li><a href="../../developers/conventions/git.html">Maven Git Convention</a></li> <li><a href="../../developers/release/index.html">Releasing a Maven project</a></li> -<li><a class="externalLink" href="https://cwiki.apache.org/confluence/display/MAVEN/Index";>Apache Maven Wiki</a></li></ul></section><section><a id="Resources_for_committers"></a> +<li><a class="externalLink" href="https://cwiki.apache.org/confluence/display/MAVEN/Index";>Apache Maven Wiki</a></li></ul></section><section> <h1>Resources for committers</h1> <ul> <li><a class="externalLink" href="http://www.apache.org/dev/";> Developer Resources</a></li> Modified: maven/website/content/guides/development/guide-maven-development.html ============================================================================== --- maven/website/content/guides/development/guide-maven-development.html (original) +++ maven/website/content/guides/development/guide-maven-development.html Sun May 12 07:42:36 2024 @@ -2,20 +2,20 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/development/guide-maven-development.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/development/guide-maven-development.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Emmanuel Venisse" /> <meta name="author" content="Trygve Laugstol" /> <meta name="author" content="Brett Porter" /> <meta name="author" content="Maarten Mulders" /> <meta name="date" content="2019-06-04" /> - <title>Maven</title> + <title>Maven â Guide to Developing Maven</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -42,10 +42,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -53,9 +51,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-maven-development.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Guide to Developing Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-maven-development.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -150,15 +147,15 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Developing_Maven"></a> +<section> <h1>Developing Maven</h1> -<p>This document describes how to get started developing Maven itself. There is a separate page describing how to <a href="./guide-building-maven.html">build Maven</a>.</p><section><a id="Finding_some_work_to_do"></a> +<p>This document describes how to get started developing Maven itself. There is a separate page describing how to <a href="./guide-building-maven.html">build Maven</a>.</p><section> <h2>Finding some work to do</h2> <p>First of all you need something to work on! Issues can be found in <a href="/issue-management.html">several JIRA projects</a>.</p> <p>Another good place to look for work is the <a class="externalLink" href="https://s.apache.org/up-for-grabs_maven";> Up for grabs</a> list. This list contains relatively simple issues that can be worked on without a lot of prerequisite knowledge. </p> -<p>When you find a issue you would like to work on, add a comment in the issue log so the core developers and other people looking for work know that someone is already working on it.</p></section><section><a id="Where.27s_the_source.3F"></a> +<p>When you find a issue you would like to work on, add a comment in the issue log so the core developers and other people looking for work know that someone is already working on it.</p></section><section> <h2>Where's the source?</h2> -<p>See <a href="/scm.html">https://maven.apache.org/scm.html</a> for information. The Maven project uses the Apache GitBox Repositories, and all of them are dual-mirrored to <a class="externalLink" href="https://github.com/apache/";> GitHub</a>.</p></section><section><a id="Don.27t_forget_tests.21"></a> +<p>See <a href="/scm.html">https://maven.apache.org/scm.html</a> for information. The Maven project uses the Apache GitBox Repositories, and all of them are dual-mirrored to <a class="externalLink" href="https://github.com/apache/";> GitHub</a>.</p></section><section> <h2>Don't forget tests!</h2> <p>You will find many unit tests. If at all possible, create or modify a unit test to demonstrate the problem, and then validate your fix.</p> <p>If you need to mock a class to write a test, use the Mockito framework. Parts of the Maven codebase predate Mockito so you will encounter existing tests that use EasyMock, PowerMock, and JMock. However, all newly written mocks should use Mockito, even if this means a module or a single class uses multiple mocking frameworks. If an existing test class has complicated legacy mock setup, you can add new Mockito based tests in a new test class. There is no requirement that all tests for a single model class must be in the same test class. It is OK to have multiple test classes per model class.</p> @@ -174,7 +171,7 @@ <li>Create a <a class="externalLink" href="https://help.github.com/en/articles/about-pull-requests";> pull request</a> to submit your contribution. Shortly after, someone will review the pull request and give you feedback on it.</li></ul> <p>A short note:</p> <ul> -<li>Make sure that you follow our code style, see <a href="#Further_Links">Further Links</a>.</li></ul></section><section><a id="Pull_request_acceptance_criteria"></a> +<li>Make sure that you follow our code style, see <a href="#Further_Links">Further Links</a>.</li></ul></section><section> <h2>Pull request acceptance criteria</h2> <p>There are a number of criteria that a pull request will be judged on:</p> <ul> @@ -182,7 +179,7 @@ <li>Whether it fits the spirit of the project. Some pull requests may be rejected as they take the project in a different direction than the current development community has chosen. This is usually discussed on an issue well before a pull request is contributed, so if you are unsure, discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.</li> <li>Whether it contains tests. It is expected that any pull request relating to functionality will be accompanied by unit tests and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.</li> <li>Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.</li></ul> -<p>Above all, don't be discouraged. These are the same requirements the current committers should hold each other to as well. And remember, your contributions are always welcome!</p></section><section><a id="Related_Projects"></a> +<p>Above all, don't be discouraged. These are the same requirements the current committers should hold each other to as well. And remember, your contributions are always welcome!</p></section><section> <h2>Related Projects</h2> <p>Maven has a few dependencies on other projects:</p> <ul> @@ -194,7 +191,7 @@ <p>You can <a class="externalLink" href="https://codehaus-plexus.github.io/modello/";>read more about Modello</a>.</p></li> <li><b>Mojo</b> <p>"Mojo" is really two things when it comes to Maven: it is both <a href="/ref/current/maven-plugin-api/">Maven's plug-in API</a> and also <a class="externalLink" href="http://www.mojohaus.org";>a separate Mojohaus project</a> hosting a lot of plugins.</p> -<p><a class="externalLink" href="http://www.mojohaus.org";>The MojoHaus Project</a> is a plugin forge for non-core Maven plugins. There is also a lower bar for becoming a part of the project.</p></li></ul></section><section><a id="Sub_Projects"></a> +<p><a class="externalLink" href="http://www.mojohaus.org";>The MojoHaus Project</a> is a plugin forge for non-core Maven plugins. There is also a lower bar for becoming a part of the project.</p></li></ul></section><section> <h2>Sub Projects</h2> <ul> <li><b>Maven Surefire</b> Modified: maven/website/content/guides/development/guide-plugin-documentation.html ============================================================================== --- maven/website/content/guides/development/guide-plugin-documentation.html (original) +++ maven/website/content/guides/development/guide-plugin-documentation.html Sun May 12 07:42:36 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/development/guide-plugin-documentation.apt.vm at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/development/guide-plugin-documentation.apt.vm at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Maven Team" /> <meta name="date" content="2006-07-06" /> - <title>Maven</title> + <title>Maven â Guide to the Plugin Documentation Standard</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -39,10 +39,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -50,9 +48,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-plugin-documentation.apt.vm";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Guide to the Plugin Documentation Standard <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/development/guide-plugin-documentation.apt.vm";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -131,19 +128,20 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Introduction"></a> -<h1>Introduction</h1><section><a id="Where_did_the_standard_come_from.3F"></a> +<section> +<h1>Introduction</h1><section> <h2>Where did the standard come from?</h2> -<p>The plugin documentation standard was created to address the frequent complain of lack of documentation, specifically on the Maven plugins. The standard was based on the suggestions made on the Maven dev mailing list with some refinements. It is a community consensus of what basic documentation a Maven plugin should have. </p></section><section><a id="Why_do_we_need_a_documentation_standard.3F"></a> +<p>The plugin documentation standard was created to address the frequent complain of lack of documentation, specifically on the Maven plugins. The standard was based on the suggestions made on the Maven dev mailing list with some refinements. It is a community consensus of what basic documentation a Maven plugin should have. </p></section><section> <h2>Why do we need a documentation standard?</h2> -<p>The standard is not a set of rules but a guide to help plugin developers document their plugins better, for the benefit of the users of the plugin. The standard also reminds the plugin developers of the important details that needs to be documented, to help speed up the adoption of the plugin.</p></section></section><section><a id="Generated_Documentation"></a> +<p>The standard is not a set of rules but a guide to help plugin developers document their plugins better, for the benefit of the users of the plugin. The standard also reminds the plugin developers of the important details that needs to be documented, to help speed up the adoption of the plugin.</p></section></section><section> <h1>Generated Documentation </h1> <p>It is recommended that you let Maven generate the basic information for the plugin to make sure that that the basic information is always accurate and synchronized with the plugin implementation. </p> <p>Documentation is generated by running </p> -<pre>mvn site</pre> -<p>It will generate a plugin site based on the information in the POM, <code>src/site</code> and other reporting plugins configured in the POM. The most important reporting plugin is the <a href="/plugins/maven-plugin-plugin/">Maven Plugin Plugin</a> which will generate the documentation for each plugin goal based on the mojo annotations. But in order for the generated site to be usable, the required information should be available to the Maven Site Plugin.</p><section><a id="POM_Elements"></a> +<div class="verbatim"> +<pre>mvn site</pre></div> +<p>It will generate a plugin site based on the information in the POM, <code>src/site</code> and other reporting plugins configured in the POM. The most important reporting plugin is the <a href="/plugins/maven-plugin-plugin/">Maven Plugin Plugin</a> which will generate the documentation for each plugin goal based on the mojo annotations. But in order for the generated site to be usable, the required information should be available to the Maven Site Plugin.</p><section> <h2>POM Elements</h2> -<p>Maven extracts the information from the POM to generate the pages under Project Information. The first step in having a good documentation is to have an accurate and visible basic project information, Maven can provide this for the plugin as long as the information in the POM is complete, descriptive and accurate.</p><section><a id="Required_Elements"></a> +<p>Maven extracts the information from the POM to generate the pages under Project Information. The first step in having a good documentation is to have an accurate and visible basic project information, Maven can provide this for the plugin as long as the information in the POM is complete, descriptive and accurate.</p><section> <h3>Required Elements</h3> <p>Minimum elements for a valid POM:</p> <ul> @@ -151,7 +149,7 @@ <li><code><groupId></code> - the package name</li> <li><code><artifactId></code> - artifact name</li> <li><code><packaging></code> - type of artifact produced by the POM</li> -<li><code><version></code> - the plugin version</li></ul></section><section><a id="Optional_Elements"></a> +<li><code><version></code> - the plugin version</li></ul></section><section> <h3>Optional Elements </h3> <p>These might be optional elements in a valid POM but they are important basic project information required by the users to effectively use the plugin:</p> <ul> @@ -160,17 +158,17 @@ <li><code><url></code> - the site of the plugin, normally <i>maven.apache.org</i> or <i>org.mojohaus</i></li> <li><code><prerequisites></code> - the minimum version of Maven required to use this plugin</li> <li><code><issueManagement></code> - describes the system used for reporting problems and modification requests -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <issueManagement> <system>jira</system> <url>http://jira.someproject.org</url> </issueManagement> [...] -</project></code></pre></li> +</project></pre></div></li> <li><code><inceptionYear></code> - year the plugin was first created</li> <li><code><mailingLists></code> - lists where other users or the developers can be contacted for help and discussions -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <mailingLists> <mailingList> @@ -185,9 +183,9 @@ </mailingList> </mailingLists> [...] -</project></code></pre></li> +</project></pre></div></li> <li><code><licenses></code> - plugin license -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <licenses> <license> @@ -197,9 +195,9 @@ </license> </licenses> [...] -</project></code></pre></li> +</project></pre></div></li> <li><code><scm></code> - the source code management configuration - a plugin without this would raise suspicion, might not be OSS -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <scm> <connection>scm:svn:http://noonecares.com/some/plugin/project/trunk</connection> @@ -207,19 +205,19 @@ <url>http://noonecares.com/viewvc/some/project/trunk/</url> </scm> [...] -</project></code></pre></li> +</project></pre></div></li> <li><code><organization></code> - the organization maintaining the plugin, just in case we need someone to blame -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <organization> <name>Noone Care Software Foundation</name> <url>http://noonecare.org/</url> </organization> [...] -</project></code></pre></li></ul></section></section><section><a id="Plugin_Configuration_Parameters"></a> +</project></pre></div></li></ul></section></section><section> <h2>Plugin Configuration Parameters</h2> <p>The Maven Plugin Plugin is responsible for generating the Plugin Info site and needs to be added to the <code><reporting></code> section unless it is already inherited from a parent POM:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <reporting> <plugins> @@ -231,19 +229,19 @@ </plugins> </reporting> [...] -</project></code></pre> +</project></pre></div> <p>The comments, annotations and plugin parameter names are extracted from the plugin source and rendered in the Plugin Info page. In order for the generated site to be useful here are some guidelines you can follow when documenting your plugin.</p> <ul> <li>all <code>@Parameter</code> fields should have a descriptive comment, informative enough that even a regular user can understand -<pre><code> [...] +<div class="verbatim source"><pre class="prettyprint linenums"> [...] /** * Put something informative here that a regular user can understand. */ @Parameter private boolean someparameter; - [...]</code></pre></li> + [...]</pre></div></li> <li>class level comment should explain what the goal does -<pre><code>[...] +<div class="verbatim source"><pre class="prettyprint linenums">[...] /** * Everything here will show up on the top of the generated plugin info page. */ @@ -254,13 +252,13 @@ public class ExampleMojo public void execute() throws MojoExecutionException, MojoFailureException { -[...]</code></pre></li> -<li>the <code>@Component</code> and <code>readonly</code> parameters are not required to have any comments but it's still a good practice to provide one</li></ul></section><section><a id="Site_Organization"></a> +[...]</pre></div></li> +<li>the <code>@Component</code> and <code>readonly</code> parameters are not required to have any comments but it's still a good practice to provide one</li></ul></section><section> <h2>Site Organization </h2> -<p>Visibility of the information is also crucial, having uniform navigation links will greatly improve the visibility of the documentations. The index page can also help emphasize important sections and pages of the plugin documentation. </p><section><a id="Site_Descriptor"></a> +<p>Visibility of the information is also crucial, having uniform navigation links will greatly improve the visibility of the documentations. The index page can also help emphasize important sections and pages of the plugin documentation. </p><section> <h3>Site Descriptor </h3> <p>The site descriptor describes the navigation links and can be found in <code>src/site/site.xml</code>. Below is the suggested site descriptor template.</p> -<pre><code><?xml version="1.0" encoding="UTF-8"?> +<div class="verbatim source"><pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> <project> <body> <menu name="Overview"> @@ -275,11 +273,12 @@ public class ExampleMojo <item name="description2" href="examples/example-two.html"/> </menu> </body> -</project></code></pre><section><a id="Navigation_Links"></a> +</project></pre></div><section> <h4>Navigation Links</h4> <ul> <li>Introduction <p>The introduction is the front page of the plugin documentation. This is a good place to place any section and pages that needs to be emphasized. It is also suggested that the generated plugin parameter configuration be linked here. Below is the suggested <code>src/site/apt/index.apt</code> template</p> +<div class="verbatim"> <pre> ------ Introduction ------ @@ -327,14 +326,14 @@ Plugin Name * {{{./examples/example-one.html}Example Description One}} * {{{./examples/example-two.html}Example Description Two}} - </pre></li> + </pre></div></li> <li>Goals <p><code>plugin-info.html</code> is generated by the Maven Plugin Plugin. Until the Maven Site Plugin is updated it would be better to pull it out to the main menu for greater visibility. This contains the goals and their descriptions with a link to the configuration parameters. The information is based on the comments and annotations of the plugin. </p></li> <li>Usage (this was previously called Howto) <p>The usage page describes the the basic use cases for the plugin goals which includes sample POM configurations and explanation of how the goals work. </p></li> <li>FAQ <p>A well documented project always collates frequently asked questions which are usually located in <code>src/site/fml/faq.fml</code>. The example below provides a template for your FAQ:</p> -<pre><code><?xml version="1.0" encoding="UTF-8"?> +<div class="verbatim source"><pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> <faqs id="FAQ" title="Frequently Asked Questions"> <part id="General"> <faq id="question"> @@ -346,20 +345,20 @@ Plugin Name </answer> </faq> </part> -</faqs></code></pre></li> +</faqs></pre></div></li> <li>Examples <p>The advanced configurations and examples not covered in the usage page is located here. Advanced users who wants to maximize the use of a plugin can check the items here. Tips on how to use the plugin effectively is also a good thing to put here.</p> <p>For examples of items under "Examples" check these plugin sites:</p> <ul> <li><a href="/plugins/maven-javadoc-plugin/">Maven Javadoc Plugin Examples</a></li> -<li><a href="/plugins/maven-war-plugin/">Maven War Plugin Examples</a></li></ul></li></ul></section></section></section><section><a id="Recommended_Configured_Reports"></a> +<li><a href="/plugins/maven-war-plugin/">Maven War Plugin Examples</a></li></ul></li></ul></section></section></section><section> <h2>Recommended Configured Reports</h2> <p>There are 2 recommended report plugins to enhance the plugin documentation, Javadoc and JXR.</p> <ul> <li>Maven Javadoc Plugin <p>Javadocs provide documentation that makes it easier for developers to know how to use a particular class. Instead of reading and understanding the actual source code, the developer can use the Javadocs instead to lookup the class attributes and methods.</p> <p>To enable javadoc for your plugin add the following to your <code>pom.xml</code></p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <build> [...] @@ -380,12 +379,12 @@ Plugin Name [...] </reporting> [...] -</project></code></pre> +</project></pre></div> <p>Check the documentation about the plugin's <a href="/plugins/maven-javadoc-plugin/javadoc-mojo.html"><code>javadoc:javadoc</code></a> goal for the advanced configurations.</p></li> <li>Maven JXR Plugin <p>The Maven JXR Plugin generates a cross-reference of the project sources. The generated cross-references are also linked to the corresponding javadoc if javadoc is generated. The cross-references is great for those who wants to better understand the inner workings of the plugin.</p> <p>To enable source code cross-references add the following to your <code>pom.xml</code></p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> [...] <build> [...] @@ -400,7 +399,7 @@ Plugin Name </plugins> </reporting> [...] -</project></code></pre> +</project></pre></div> <p>Check the <a href="/plugins/maven-jxr-plugin/jxr-mojo.html">JXR configuration page</a> for the possible configuration parameters.</p></li></ul></section></section> </main> </div>
