Return-Path: X-Original-To: apmail-maven-commits-archive@www.apache.org Delivered-To: apmail-maven-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id D961F9CBA for ; Mon, 10 Dec 2012 08:18:33 +0000 (UTC) Received: (qmail 93093 invoked by uid 500); 10 Dec 2012 08:18:33 -0000 Delivered-To: apmail-maven-commits-archive@maven.apache.org Received: (qmail 92959 invoked by uid 500); 10 Dec 2012 08:18:33 -0000 Mailing-List: contact commits-help@maven.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@maven.apache.org Delivered-To: mailing list commits@maven.apache.org Received: (qmail 92664 invoked by uid 99); 10 Dec 2012 08:18:32 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 10 Dec 2012 08:18:32 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 10 Dec 2012 08:18:29 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id DD5DB2388A66 for ; Mon, 10 Dec 2012 08:18:02 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r841370 [3/47] - in /websites/staging/maven/trunk/content: ./ ant/ background/ css/ developers/ developers/conventions/ developers/release/ developers/website/ docs/ docs/2.0.1/ docs/2.0.10/ docs/2.0.11/ docs/2.0.2/ docs/2.0.3/ docs/2.0.4/ ... Date: Mon, 10 Dec 2012 08:17:44 -0000 To: commits@maven.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20121210081802.DD5DB2388A66@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: websites/staging/maven/trunk/content/css/maven-base.css ============================================================================== --- websites/staging/maven/trunk/content/css/maven-base.css (added) +++ websites/staging/maven/trunk/content/css/maven-base.css Mon Dec 10 08:17:24 2012 @@ -0,0 +1,156 @@ +body { + margin: 0px; + padding: 0px; +} +img { + border:none; +} +table { + padding:0px; + width: 100%; + margin-left: -2px; + margin-right: -2px; +} +acronym { + cursor: help; + border-bottom: 1px dotted #feb; +} +table.bodyTable th, table.bodyTable td { + padding: 2px 4px 2px 4px; + vertical-align: top; +} +div.clear{ + clear:both; + visibility: hidden; +} +div.clear hr{ + display: none; +} +#bannerLeft, #bannerRight { + font-size: xx-large; + font-weight: bold; +} +#bannerLeft img, #bannerRight img { + margin: 0px; +} +.xleft, #bannerLeft img { + float:left; +} +.xright, #bannerRight { + float:right; +} +#banner { + padding: 0px; +} +#banner img { + border: none; +} +#breadcrumbs { + padding: 3px 10px 3px 10px; +} +#leftColumn { + width: 170px; + float:left; + overflow: auto; + padding-bottom: 3px; /* IE-9 scrollbar-fix */ +} +#bodyColumn { + margin-right: 1.5em; + margin-left: 197px; +} +#legend { + padding: 8px 0 8px 0; +} +#navcolumn { + padding: 8px 4px 0 8px; +} +#navcolumn h5 { + margin: 0; + padding: 0; + font-size: small; +} +#navcolumn ul { + margin: 0; + padding: 0; + font-size: small; +} +#navcolumn li { + list-style-type: none; + background-image: none; + background-repeat: no-repeat; + background-position: 0 0.4em; + padding-left: 16px; + list-style-position: outside; + line-height: 1.2em; + font-size: smaller; +} +#navcolumn li.expanded { + background-image: url(../images/expanded.gif); +} +#navcolumn li.collapsed { + background-image: url(../images/collapsed.gif); +} +#navcolumn li.none { + text-indent: -1em; + margin-left: 1em; +} +#poweredBy { + text-align: center; +} +#navcolumn img { + margin-top: 10px; + margin-bottom: 3px; +} +#poweredBy img { + display:block; + margin: 20px 0 20px 17px; +} +#search img { + margin: 0px; + display: block; +} +#search #q, #search #btnG { + border: 1px solid #999; + margin-bottom:10px; +} +#search form { + margin: 0px; +} +#lastPublished { + font-size: x-small; +} +.navSection { + margin-bottom: 2px; + padding: 8px; +} +.navSectionHead { + font-weight: bold; + font-size: x-small; +} +.section { + padding: 4px; +} +#footer { + padding: 3px 10px 3px 10px; + font-size: x-small; +} +#breadcrumbs { + font-size: x-small; + margin: 0pt; +} +.source { + padding: 12px; + margin: 1em 7px 1em 7px; +} +.source pre { + margin: 0px; + padding: 0px; +} +#navcolumn img.imageLink, .imageLink{ + padding-left: 0px; + padding-bottom: 0px; + padding-top: 0px; + padding-right: 2px; + border: 0px; + margin: 0px; +} Added: websites/staging/maven/trunk/content/css/maven-theme.css ============================================================================== --- websites/staging/maven/trunk/content/css/maven-theme.css (added) +++ websites/staging/maven/trunk/content/css/maven-theme.css Mon Dec 10 08:17:24 2012 @@ -0,0 +1,217 @@ +/* + * 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. + */ + +body { + background-color: #fff; + font-family: Verdana, Helvetica, Arial, sans-serif; + margin-left: auto; + margin-right: auto; + background-repeat: repeat-y; + font-size: 13px; + padding: 0px; +} +td, select, input, li{ + font-family: Verdana, Helvetica, Arial, sans-serif; + font-size: 12px; + color:#333333; +} +code{ + font-size: 12px; +} +a { + text-decoration: none; +} +a:link { + color:#47a; +} +a:visited { + color:#68a; +} +a:active, a:hover { + color:#990000; +} +#legend li.externalLink { + background: url(../images/external.png) left top no-repeat; + padding-left: 18px; +} +a.externalLink, a.externalLink:link, a.externalLink:visited, a.externalLink:active, a.externalLink:hover { + background: url(../images/external.png) right center no-repeat; + padding-right: 18px; +} +#legend li.newWindow { + background: url(../images/newwindow.png) left top no-repeat; + padding-left: 18px; +} +a.newWindow, a.newWindow:link, a.newWindow:visited, a.newWindow:active, a.newWindow:hover { + background: url(../images/newwindow.png) right center no-repeat; + padding-right: 18px; +} +h2 { + font-size: 17px; + color: #333333; +} +h3 { + padding: 4px 4px 4px 24px; + color: #666; + background-color: #ccc; + font-weight: bold; + font-size: 14px; + background-image: url(../images/h3.jpg); + background-repeat: no-repeat; + background-position: left bottom; +} +p { + line-height: 1.3em; + font-size: 12px; + color: #000; +} +#breadcrumbs { + height: 13px; + background-image: url(../images/breadcrumbs.jpg); + padding: 5px 10px 14px 20px; +} +* html #breadcrumbs { + padding-bottom: 8px; +} +#leftColumn { + margin: 10px 0 10px 0; + border-top-color: #ccc; + border-top-style: solid; + border-top-width: 1px; + border-right-color: #ccc; + border-right-style: solid; + border-right-width: 1px; + border-bottom-color: #ccc; + border-bottom-style: solid; + border-bottom-width: 1px; + padding-right: 5px; + padding-left: 5px; +} +#navcolumn h5 { + font-size: smaller; + border-bottom: 1px solid #aaaaaa; + padding-top: 2px; + padding-left: 9px; + color: #49635a; + background-image: url(../images/h5.jpg); + background-repeat: no-repeat; + background-position: left bottom; +} + +table.bodyTable th { + color: white; + background-color: #bbb; + text-align: left; + font-weight: bold; +} + +table.bodyTable th, table.bodyTable td { + font-size: 11px; +} + +table.bodyTable tr.a { + background-color: #ddd; +} + +table.bodyTable tr.b { + background-color: #eee; +} + +table.bodyTable tr.a:hover, table.bodyTable tr.b:hover { + background: #dfe3db; +} + +.source { + border: 1px solid #999; + overflow:auto +} +dt { + padding: 4px 4px 4px 24px; + color: #333333; + background-color: #ccc; + font-weight: bold; + font-size: 14px; + background-image: url(../images/h3.jpg); + background-repeat: no-repeat; + background-position: left bottom; +} +.subsectionTitle { + font-size: 13px; + font-weight: bold; + color: #666; + +} + +table { + font-size: 10px; +} +.xright a:link, .xright a:visited, .xright a:active { + color: #666; +} +.xright a:hover { + color: #003300; +} +#banner { + height: 93px; + background: url(../images/banner.jpg); +} +#navcolumn ul { + margin: 5px 0 15px -0em; +} +#navcolumn ul a { + color: #333333; +} +#navcolumn ul a:hover { + color: red; +} +#intro { + border: solid #ccc 1px; + margin: 6px 0px 0px 0px; + padding: 10px 40px 10px 40px; +} +.subsection { + margin-left: 3px; + color: #333333; +} + +.subsection p { + font-size: 12px; +} +#footer { + padding: 10px; + margin: 20px 0px 20px 0px; + border-top: solid #ccc 1px; + color: #333333; +} + +.errormark, .warningmark, .donemark, .infomark { + background: url(../images/icon_error_sml.gif) no-repeat; +} + +.warningmark { + background-image: url(../images/icon_warning_sml.gif); +} + +.donemark { + background-image: url(../images/icon_success_sml.gif); +} + +.infomark { + background-image: url(../images/icon_info_sml.gif); +} Added: websites/staging/maven/trunk/content/css/print.css ============================================================================== --- websites/staging/maven/trunk/content/css/print.css (added) +++ websites/staging/maven/trunk/content/css/print.css Mon Dec 10 08:17:24 2012 @@ -0,0 +1,7 @@ +#banner, #footer, #leftcol, #breadcrumbs, .docs #toc, .docs .courtesylinks, #leftColumn, #navColumn { + display: none !important; +} +#bodyColumn, body.docs div.docs { + margin: 0 !important; + border: none !important +} Added: websites/staging/maven/trunk/content/css/site.css ============================================================================== --- websites/staging/maven/trunk/content/css/site.css (added) +++ websites/staging/maven/trunk/content/css/site.css Mon Dec 10 08:17:24 2012 @@ -0,0 +1,38 @@ +a.externalLink, a.externalLink:link, a.externalLink:visited, a.externalLink:active, a.externalLink:hover { + background: none; + padding-right: 0; +} + +body ul { + list-style-type: square; +} + +#downloadbox { + float: right; + margin-left: 2em; + padding-left: 1em; + padding-right: 1em; + padding-bottom: 1em; + border: 1px solid #999; + background-color: #eee; + width: 17.5em; +} + +#downloadbox h5 { + color: #000; + margin: 0; + border-bottom: 1px solid #aaaaaa; + font-size: smaller; + padding: 0; + margin-top: 1em; +} + +#downloadbox p { + margin-top: 1em; + margin-bottom: 0; +} + +#downloadbox li { + text-indent: inherit; +} + Added: websites/staging/maven/trunk/content/developers/.htaccess ============================================================================== --- websites/staging/maven/trunk/content/developers/.htaccess (added) +++ websites/staging/maven/trunk/content/developers/.htaccess Mon Dec 10 08:17:24 2012 @@ -0,0 +1,4 @@ +RedirectMatch permanent (.*)/developers/committer-testing-plugins.html $1/plugin-developers/plugin-testing.html +RedirectMatch permanent (.*)/developers/committer-documentation-plugins.html $1/plugin-developers/plugin-documenting.html +RedirectMatch permanent (.*)/developers/release/maven-proper-release.html $1/developers/release/maven-core-release.html +RedirectMatch permanent (.*)/developers/release/apache-release.html http://www.apache.org/dev/publishing-maven-artifacts.html Added: websites/staging/maven/trunk/content/developers/committer-environment.html ============================================================================== --- websites/staging/maven/trunk/content/developers/committer-environment.html (added) +++ websites/staging/maven/trunk/content/developers/committer-environment.html Mon Dec 10 08:17:24 2012 @@ -0,0 +1,269 @@ + + + + + Maven - Developers centre - Commiter Environment + + + + + + + + + + + + + +
+ +
+
+
+

Introduction

This document is intended to set up the Maven committer environment.

Source File Encoding

When editing source files, make sure you use the right file encoding. For the Maven project, UTF-8 has been chosen as the default file encoding. UTF-8 is an encoding scheme for the Unicode character set and as such allows to encode all characters that Java can handle. The source files should not contain the byte order mark (BOM). There can be exceptions to this general rule, e.g. properties files are usually encoded using ISO-8859-1 as per the JRE API, so please keep this in mind, too.

Subversion Configuration

Before committing files in subversion repository, you need to read the Committer Subversion Access document and you must set your svn client with this properties file: svn-eol-style.txt

Maven Code Style

The following sections show how to set up the code style for Maven in IDEA and Eclipse. It is strongly preferred that patches use this style before they are supplied.

IntelliJ IDEA 4.5+

Download maven-idea-codestyle.xml and copy it to ~/.IntelliJIDEA/config/codestyles then restart IDEA. On Windows, try C:\Documents and Settings\<username>\.IntelliJIDEA\config\codestyles

After this, restart IDEA and open the settings to select the new code style.

Eclipse 3.2+

Download maven-eclipse-codestyle.xml.

After this, select Window > Preferences, and open up the configuration for Java > Code Style > Code Formatter. Click on the button labeled Import... and select the file you downloaded. Give the style a name, and click OK.

Setting up SSH public/private keys

By default, SSH (Secure Shell) asks you to enter your password each time, i.e.:

>ssh YOUR_APACHE_USERNAME@people.apache.org
+Password:

SSH can be set up with public/private key pairs so that you don't have to type the password each time. You need to execute the following on your development machine:

> cd ~/.ssh
+> ssh-keygen -t dsa -f YOUR_APACHE_USERNAME@apache.org -C YOUR_APACHE_USERNAME@apache.org
+Generating public/private dsa key pair.
+Enter passphrase (empty for no passphrase): (just type return)
+Enter same passphrase again: (just type return)
+Your identification has been saved in YOUR_APACHE_USERNAME@apache.org.
+Your public key has been saved in YOUR_APACHE_USERNAME@apache.org.pub.
+The key fingerprint is:
+0c:16:c7:44:9e:a6:2c:c0:8a:87:04:07:a0:5b:94:d2 YOUR_APACHE_USERNAME@apache.org

Then, paste the content of the local ~/.ssh/YOUR_APACHE_USERNAME.pub file into the file /home/YOUR_APACHE_USERNAME/.ssh/authorized_keys on the Apache remote host.

Note: under Cygwin, it is located at {cygwin.install.path}\home\YOUR_MACHINE_USERNAME\.ssh. You need to copy the content of {cygwin.install.path}\home\YOUR_MACHINE_USERNAME\.ssh into C:\Documents and Settings\YOUR_MACHINE_USERNAME\.ssh for Maven.

You also need to modify the ~/.ssh/config to use this identity file when communicating with *.apache.org

Host *.apache.org
+User=YOUR_APACHE_USERNAME
+IdentityFile=~/.ssh/YOUR_APACHE_USERNAME@apache.org

To test the installation, try to log in again on Apache. You should not be asked for your password any more.

 > ssh YOUR_APACHE_USERNAME@people.apache.org
+Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
+        The Regents of the University of California.  All rights reserved.
+
+FreeBSD 8.2-RELEASE-p4 (GENERIC) #1 r226043: Wed Oct  5 18:45:41 UTC 2011
+
+This is minotaur.apache.org (a.k.a. people.apache.org). 
+...
+YOUR_APACHE_USERNAME@minotaur:~$

Useful software

The Maven Team uses several software. Here is a partial list:

  • Cygwin: collection of free software tools to allow various versions of Microsoft Windows to act somewhat like a Unix system
  • WinSCP: SFTP client for Windows.
  • TortoiseSVN: Subversion client, implemented as a Windows shell extension.
  • GnuPG: GNU Privacy Guard.
+
+
+
+
+
+ + + Added: websites/staging/maven/trunk/content/developers/committer-settings.html ============================================================================== --- websites/staging/maven/trunk/content/developers/committer-settings.html (added) +++ websites/staging/maven/trunk/content/developers/committer-settings.html Mon Dec 10 08:17:24 2012 @@ -0,0 +1,300 @@ + + + + + Maven - Developers centre - Committer Settings + + + + + + + + + + + + + + +
+ +
+
+
+

Introduction

This document is intended to set up the Maven committer settings, i.e. the ${user.home}/.m2/settings.xml.

Enable Apache Servers

Maven uses several servers configuration to deploy snapshots, releases and documentation on the Apache servers. You need to tell to Maven what your Apache username is. Please note that the servers now use your LDAP credentials, which may differ from your old SVN credentials.

It is highly recommended to use Maven's password encryption capabilities for your passwords.

<settings>
+  ...
+  <servers>
+    <!-- To publish a snapshot of some part of Maven -->
+    <server>
+      <id>apache.snapshots.https</id>
+      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
+      <password> <!-- YOUR APACHE LDAP PASSWORD --> </password>
+    </server>
+    <!-- To publish a website of some part of Maven -->
+    <server>
+      <id>apache.website</id>
+      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
+      <!-- Either
+      <password>...</password>
+      or
+      <privateKey>...</privateKey>
+      ---> 
+      <filePermissions>664</filePermissions>
+      <directoryPermissions>775</directoryPermissions>
+    </server>
+    <!-- To stage a release of some part of Maven -->
+    <server>
+      <id>apache.releases.https</id>
+      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
+      <password> <!-- YOUR APACHE LDAP PASSWORD --> </password>
+    </server>
+    <!-- To stage a website of some part of Maven -->
+    <server>
+      <id>stagingSite</id> <!-- must match hard-coded repository identifier in site:stage-deploy -->
+      <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
+      <filePermissions>664</filePermissions>
+      <directoryPermissions>775</directoryPermissions>
+    </server>
+    ...
+  </servers>
+</settings>

You also need to be a member of the group apcvs and maven on people.apache.org.

Enable sending announcement e-mails

To be able to send out announcements of Maven releases you need to add a couple of properties to the apache-release profile.

<settings>
+  ...
+  <profiles>
+    <profile>
+      <id>apache-release</id>
+      <properties>
+        <apache.availid> <!-- YOUR APACHE LDAP USERNAME --> </apache.availid>
+        <smtp.host> <!-- YOUR SMTP SERVER --> </smtp.host>
+      </properties>
+    </profile>
+    ...
+  </profiles>
+</settings>
+
+
+
+
+
+ + + Added: websites/staging/maven/trunk/content/developers/conventions/code.html ============================================================================== --- websites/staging/maven/trunk/content/developers/conventions/code.html (added) +++ websites/staging/maven/trunk/content/developers/conventions/code.html Mon Dec 10 08:17:24 2012 @@ -0,0 +1,364 @@ + + + + + Maven - Maven Code Style And Code Conventions + + + + + + + + + + + + + + +
+ +
+
+
+

Maven Code Style And Code Conventions

This document describes how developers and contributors should write code. The reasoning of these styles and conventions is mainly for consistency, readability and maintainability reasons.

Generic Code Style And Convention

All working files (java, xml, others) should respect the following conventions:

  • License Header: Always add the current ASF license header in all versionned files.
  • Trailing Whitespaces: Remove all trailing whitespaces. If your are an Eclipse user, you could use the Anyedit Eclipse Plugin.

and the following style:

  • Indentation: Never use tabs!
  • Line wrapping: Always use a 120-column line width.

Note: The specific styles and conventions, listed in the next sections, could override these generic rules.

Java

Java Code Style

The Maven style for Java is mainly:

  • White space: One space after control statements and between arguments (i.e. if ( foo ) instead of if(foo)), myFunc( foo, bar, baz ) instead of myFunc(foo,bar,baz)). No spaces after methods names (i.e. void myMethod(), myMethod( "foo" ))
  • Indentation: Always use 4 space indents and never use tabs!
  • Blocks: Always enclose with a new line brace.
  • Line wrapping: Alway s use a 120-column line width for Java code and Javadoc.
  • Readingness: Specify code grouping members, if needed. For instance in a Mojo class, you could have:
    public class MyMojo
+{
+    // ----------------------------------------------------------------------
+    // Mojo components
+    // ----------------------------------------------------------------------
+
+    /**
+     * Artifact factory.
+     *
+     * @component
+     */
+    private ArtifactFactory artifactFactory;
+
+    ...
+
+    // ----------------------------------------------------------------------
+    // Mojo parameters
+    // ----------------------------------------------------------------------
+
+    /**
+     * The POM.
+     *
+     * @parameter expression="${project}"
+     * @required
+     */
+    private MavenProject project;
+
+    ...
+
+    // ----------------------------------------------------------------------
+    // Mojo options
+    // ----------------------------------------------------------------------
+    ...
+
+    // ----------------------------------------------------------------------
+    // Public methods
+    // ----------------------------------------------------------------------
+
+    /**
+     * {@inheritDoc}
+     */
+    public void execute()
+        throws MojoExecutionException
+    {
+      ...
+    }
+
+    // ----------------------------------------------------------------------
+    // Protected methods
+    // ----------------------------------------------------------------------
+    ...
+
+    // ----------------------------------------------------------------------
+    // Private methods
+    // ----------------------------------------------------------------------
+    ...
+
+    // ----------------------------------------------------------------------
+    // Static methods
+    // ----------------------------------------------------------------------
+    ...
+}

The following sections show how to set up the code style for Maven in IDEA and Eclipse. It is strongly preferred that patches use this style before they are applied.

IntelliJ IDEA 4.5+

Download maven-idea-codestyle.xml and copy it to ~/.IntelliJIDEA/config/codestyles then restart IDEA. On Windows, try C:\Documents and Settings<username>\.IntelliJIDEA\config\codestyles

After this, restart IDEA and open the settings to select the new code style.

Eclipse 3.2+

Download maven-eclipse-codestyle.xml.

After this, select Window > Preferences, and open up the configuration for Java > Code Style > Code Formatter. Click on the button labeled Import... and select the file you downloaded. Give the style a name, and click OK.

Java Code Convention

For consistency reasons, our Java code convention is mainly:

  • Naming: Constants (i.e. static final members) values should always be in upper case. Using short, descriptive names for classes and methods.
  • Organization: Avoid using a lot of public inner classes. Prefer interfaces instead of default implementation.
  • Modifier: Avoid using final modifier on all member variables and arguments. Prefer using private or protected member instead of public member.
  • Exceptions: Throw meaningful exceptions to makes debugging and testing more easy.
  • Documentation: Document public interfaces well, i.e. all non-trivial public and protected functions should include Javadoc that indicates what it does. Note: it is an ongoing convention for the Maven Team.
  • Testing: All non-trivial public classes should include corresponding unit or IT tests.

JavaDoc Convention

TO BE DISCUSSED

XML

XML Code Style

The Maven style for XML files is mainly:

  • Indentation: Always use 2 space indents, unless you're wrapping a new XML tags line in which case you should indent 4 spaces.
  • Line Breaks: Always use a new line with indentation for complex XML types and no line break for simple XML types. Always use a new line to separate XML sections or blocks, for instance:
    <aTag>
+  <simpleType>This is a simple type</simpleType>
+
+  <complexType>
+    <simpleType>This is a complex type</simpleType>
+  </complexType>
+</aTag>

    In some cases, adding comments could improve the readability of blocks, for instance:

        <!-- Simple XML documentation                                               -->

    or

        <!-- ====================================================================== -->
+    <!-- Block documentation                                                    -->
+    <!-- ====================================================================== -->

Generic XML Code Convention

No generic code convention exists yet for XML files.

POM Code Convention

The team has voted during the end of June 2008 to follow a specific POM convention to ordering POM elements. The consequence of this vote is that the Maven project descriptor is no more considered as the reference for the ordering.

The following is the recommended ordering for all Maven POM files:

<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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion/>
+
+  <parent/>
+
+  <groupId/>
+  <artifactId/>
+  <version/>
+  <packaging/>
+
+  <name/>
+  <description/>
+  <url/>
+  <inceptionYear/>
+  <organization/>
+  <licenses/>
+
+  <developers/>
+  <contributors/>
+
+  <mailingLists/>
+
+  <prerequisites/>
+
+  <modules/>
+
+  <scm/>
+  <issueManagement/>
+  <ciManagement/>
+  <distributionManagement/>
+
+  <properties/>
+
+  <dependencyManagement/>
+  <dependencies/>
+
+  <repositories/>
+  <pluginRepositories/>
+
+  <build/>
+
+  <reporting/>
+
+  <profiles/>
+</project>

Comments:

  1. The <project/> element is always on one line.
  2. The blocks are voluntary separated by a new line to improve the readingness.
  3. The dependencies in <dependencies/> and <dependencyManagement/> tags have no specific ordering. Developers are free to choose the ordering, but grouping dependencies by topics (like groupId i.e. org.apache.maven) is a good practice.

Note: The team plans to create a Maven plugin with reorder and reformat goals (See MOJO-928).

XDOC Code Convention

For consistency and readability reasons, XDOC files should respect:

  • Metadata: Always specify metadata in the <properties/> tag.
  • Sections: Always use a new line with indentat ion for <section/> tags.

FML Code Convention

For readability reasons, FML files should respect:

  • FAQ: Always use a new line with indentation for <faq/> tags.
+
+
+
+
+
+ + + Added: websites/staging/maven/trunk/content/developers/conventions/git.html ============================================================================== --- websites/staging/maven/trunk/content/developers/conventions/git.html (added) +++ websites/staging/maven/trunk/content/developers/conventions/git.html Mon Dec 10 08:17:24 2012 @@ -0,0 +1,280 @@ + + + + + Maven - Maven Git Convention + + + + + + + + + + + + + + +
+ +
+
+
+

Maven Git Convention

This document describes how developers should use Git, our SCM.

Git migration

ETA of git migration is here: https://cwiki.apache.org/confluence/display/MAVEN/Git+Migration

Git Configuration

TODO

Commit Message Template

Commits should be focused on one issue at a time, because that makes it easier for others to review the commit.

A commit message should use this template:

[ISSUE-1] <<Summary field from JIRA>>
+Submitted by: <<Name of non-committer>>
+
+o Comments

Where:

  • ISSUE-1 can be omitted if there was no relevant JIRA issue, though you are strongly encouraged to create one for significant changes.
  • Submitted by only needs to be specified when a patch is being applied for a non-committer.
  • Comments some optional words about the solution.

eg:

[MNG-1456] Added the foo to the bar
+Submitted by: Baz Bazman
+
+o Applied without change

Apply User Patch

By default, the committer should apply the patch without any major modifications. In a second step, the committer could apply any changes as usual.

Edit Commit Message

 git commit --amend to edit last commit comment

Workflow

Workflow for svn folks is something like :

 $ git pull
+ $ hack hack hack
+ $ git push
+ // fails, because someone else has already pushed to master
+ $ git pull
+ // this creates some merges
+ $ git push

A more quiet workflow :

$ git pull
+$ hack hack hack
+$ git push
+// fails, because someone else has already pushed to master
+$ git fetch
+// this moves 'origin/master'
+$ git rebase origin/master
+// this reapplies your local changes on top of origin/master
+$ git push

Other useful Git commands while developing

If you've done a chunk of work and you would like ditch your changes and start from scratch use this command to revert to the original checkout:

$ git checkout .

TODO .gitignore

power-git checkout

This checkout is typical for highly experienced git users, and may serve as inspiration for others; as usual the best way to learn is by doing. Sample shown for maven-surefire

Go to https://github.com/apache/maven-surefire and fork surefire to your own github account.

Starting with nothing (no existing clone)

git clone https://github.com/<youraccount>/maven-surefire.git
+git remote add apache https://git-wip-us.apache.org/repos/asf/maven-surefire.git
+git remote add asfgithub https://github.com/apache/maven-surefire.git
+git config --add remote.asfgithub.fetch "+refs/pull/*/head:refs/remotes/asfgithub/pr/*"
+git fetch --all

(You may consider adding --global to the git config statement above to always fetch pull requests for any remote named "asfgithub")

In this setup, running "git push" will normally push to your personal github account. Furthermore, all pull requests from github are also fetched to your local clone, use

gitk --all

to try to make some sense of it all. This is an important command to understand! (gitk may need to be installed additionally)

If you're working on the master branch, you can do stuff like this:

git push # your github account
+git push apache # the authorative apache repo

Using your github account as a storage for half-finished work is excellent if you switch between multiple computers, always push to github before leaving your current computer and start by pulling at the next computer.

To merge a pull request

git merge pr/10 # merge pull request number 10 from asf@github into master
+git push apache # upload to apache

Or if you're comfortable with rebasing;

+git checkout pr/10
+git rebase apache/master
+git push apache
+
+
+
+
+
+ + +