You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by br...@apache.org on 2014/08/27 15:01:37 UTC
svn commit: r1620885 - in /commons/proper/commons-build-plugin/trunk/src:
main/resources/commons-xdoc-templates/ main/scripts/ site/ site/xdoc/
Author: britter
Date: Wed Aug 27 13:01:37 2014
New Revision: 1620885
URL: http://svn.apache.org/r1620885
Log:
Add a mojo for generating a CONTRIBUTING.md containing informations for GitHub contributors.
Added:
commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/contributing-md-template.md
commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md-mojo.xml (with props)
commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md.xml (with props)
Modified:
commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml
commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml
commons/proper/commons-build-plugin/trunk/src/site/site.xml
commons/proper/commons-build-plugin/trunk/src/site/xdoc/index.xml
Added: commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/contributing-md-template.md
URL: http://svn.apache.org/viewvc/commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/contributing-md-template.md?rev=1620885&view=auto
==============================================================================
--- commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/contributing-md-template.md (added)
+++ commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/contributing-md-template.md Wed Aug 27 13:01:37 2014
@@ -0,0 +1,96 @@
+<!---
+ 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.
+-->
+<!---
+ +======================================================================+
+ |**** ****|
+ |**** THIS FILE IS GENERATED BY THE COMMONS BUILD PLUGIN ****|
+ |**** DO NOT EDIT DIRECTLY ****|
+ |**** ****|
+ +======================================================================+
+ | TEMPLATE FILE: mail-lists-template.xml |
+ | commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates |
+ +======================================================================+
+ | |
+ | 1) Re-generate using: mvn commons:contributing-md |
+ | |
+ | 2) Set the following properties in the component's pom: |
+ | - commons.jira.id (required, alphabetic, upper case) |
+ | |
+ | 3) Example Properties |
+ | |
+ | <properties> |
+ | <commons.jira.id>MATH</commons.jira.id> |
+ | </properties> |
+ | |
+ +======================================================================+
+--->
+Contributing to @NAME@
+======================
+
+You have found a bug or you have an idea for a cool new feature? Contributing code is a great way to give something back to
+the open source community. Before you dig right into the code there are a few guidelines that we need contributors to
+follow so that we can have a chance of keeping on top of things.
+
+Getting Started
+---------------
+
++ Make sure you have a [JIRA account](https://issues.apache.org/jira/).
++ Make sure you have a [GitHub account](https://github.com/signup/free).
++ If you're planning to implement a new feature it makes sense to discuss you're changes on the [dev list](http://commons.apache.org/proper/@ARTIFACTID@/mail-lists.html) first. This way you can make sure you're not wasting your time on something that isn't considered to be in @NAME@'s scope.
++ Submit a ticket for your issue, assuming one does not already exist.
+ + Clearly describe the issue including steps to reproduce when it is a bug.
+ + Make sure you fill in the earliest version that you know has the issue.
++ Fork the repository on GitHub.
+
+Making Changes
+--------------
+
++ Create a topic branch from where you want to base your work (this is usually the master/trunk branch).
++ Make commits of logical units.
++ Respect the original code style:
+ + Only use spaces for indentation.
+ + Create minimal diffs - disable on save actions like reformat source code or organize imports. If you feel the source code should be reformatted create a separate PR for this change.
+ + Check for unnecessary whitespace with git diff --check before committing.
++ Make sure your commit messages are in the proper format. Your commit message should contain the key of the JIRA issue.
++ Make sure you have added the necessary tests for your changes.
++ Run all the tests with `mvn clean test` to assure nothing else was accidentally broken.
+
+Making Trivial Changes
+----------------------
+
+For changes of a trivial nature to comments and documentation, it is not always necessary to create a new ticket in JIRA.
+In this case, it is appropriate to start the first line of a commit with '(doc)' instead of a ticket number.
+
+Submitting Changes
+------------------
+
++ Sign the [Contributor License Agreement][cla].
++ Push your changes to a topic branch in your fork of the repository.
++ Submit a pull request to the repository in the apache organization.
++ Update your JIRA ticket and include a link to the pull request in the ticket.
+
+Additional Resources
+--------------------
+
++ [Contributing patches](http://commons.apache.org/patches.html)
++ [@NAME@ JIRA project page](https://issues.apache.org/jira/browse/@JIRA_ID@)
++ [Contributor License Agreement][cla]
++ [General GitHub documentation](http://help.github.com/)
++ [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
++ #apachecommons IRC channel on freenode.org
+
+[cla]:http://www.apache.org/licenses/#clas
Modified: commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml?rev=1620885&r1=1620884&r2=1620885&view=diff
==============================================================================
--- commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml (original)
+++ commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml Wed Aug 27 13:01:37 2014
@@ -334,4 +334,37 @@
</copy>
</target>
+
+ <!-- ========== Generate CONTRIBUTING.md file ================================ -->
+
+ <target name="contributing-md" description="Generate CONTRIBUTING.md">
+
+ <echo level="${level}" message="----- commons:readme-md - Parameters - START -----" />
+ <echo level="${level}" message="project.name : ${project.name}" />
+ <echo level="${level}" message="project.artifactId : ${project.artifactId}" />
+ <echo level="${level}" message="commons.jira.id : ${commons.jira.id}" />
+ <echo level="${level}" message="----- commons:readme-md - Parameters - END -----" />
+
+ <echo level="info" message="*** Generating ${project.name} CONTRIBUTING.md ***" />
+
+ <!-- Create a temporary directory to load the template files into -->
+ <mkdir dir="${commonsMojoTempDir}"/>
+
+ <!-- Load the contributing-md template from mojo resources to temp directory -->
+ <loadresource property="contributing-md">
+ <javaresource name="${commonsMojoXdocDir}/contributing-md-template.md"/>
+ </loadresource>
+ <echo message="${contributing-md}" file="${commonsMojoTempDir}/contributing-md-template.md" append="false" />
+
+ <!-- Copy the mail-lists template filtering to replace properties -->
+ <copy file="${commonsMojoTempDir}/contributing-md-template.md" tofile="CONTRIBUTING.md" overwrite="true">
+ <filterset>
+ <filter token="NAME" value="${project.name}"/>
+ <filter token="ARTIFACTID" value="${project.artifactId}"/>
+ <filter token="JIRA_ID" value="${commons.jira.id}"/>
+ </filterset>
+ </copy>
+
+ </target>
+
</project>
Modified: commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml?rev=1620885&r1=1620884&r2=1620885&view=diff
==============================================================================
--- commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml (original)
+++ commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml Wed Aug 27 13:01:37 2014
@@ -318,5 +318,40 @@
</parameter>
</parameters>
</mojo>
+ <mojo>
+ <goal>contributing-md</goal>
+ <call>contributing-md</call>
+ <description>Commons Build Ant Mojo: Generate CONTRIBUTING.md</description>
+ <requiresProject>true</requiresProject>
+ <parameters>
+ <parameter>
+ <name>project.name</name>
+ <property>project.name</property>
+ <required>true</required>
+ <readonly>true</readonly>
+ <defaultValue>${project.name}</defaultValue>
+ <type>java.lang.String</type>
+ <description>The name of the project currently being built.</description>
+ </parameter>
+ <parameter>
+ <name>project.artifactId</name>
+ <property>project.artifactId</property>
+ <required>true</required>
+ <readonly>true</readonly>
+ <defaultValue>${project.artifactId}</defaultValue>
+ <type>java.lang.String</type>
+ <description>The artifactId of the project currently being built.</description>
+ </parameter>
+ <parameter>
+ <name>commons.jira.id</name>
+ <property>commons.jira.id</property>
+ <required>true</required>
+ <readonly>false</readonly>
+ <defaultValue>${commons.jira.id}</defaultValue>
+ <type>java.lang.String</type>
+ <description>The external JIRA id for the project (alphabetic, upper case)</description>
+ </parameter>
+ </parameters>
+ </mojo>
</mojos>
</pluginMetadata>
Modified: commons/proper/commons-build-plugin/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-build-plugin/trunk/src/site/site.xml?rev=1620885&r1=1620884&r2=1620885&view=diff
==============================================================================
--- commons/proper/commons-build-plugin/trunk/src/site/site.xml (original)
+++ commons/proper/commons-build-plugin/trunk/src/site/site.xml Wed Aug 27 13:01:37 2014
@@ -46,6 +46,10 @@
<item name="readme-md" href="/readme-md.html"/>
<item name="properties" href="/readme-md-mojo.html"/>
</item>
+ <item name="CONTRIBUTING.md" href="/contributing-md.html">
+ <item name="contributing-md" href="/contributing-md.html"/>
+ <item name="properties" href="/contributing-md-mojo.html"/>
+ </item>
<item name="Help" href="/development.html">
<item name="Issue Tracking" href="/issue-tracking.html"/>
<item name="Development" href="/development.html"/>
Added: commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md-mojo.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md-mojo.xml?rev=1620885&view=auto
==============================================================================
--- commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md-mojo.xml (added)
+++ commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md-mojo.xml Wed Aug 27 13:01:37 2014
@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<!--
+ $HeadURL: https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md-mojo.xml $
+ $Revision: 1619060 $
+ -->
+<document>
+ <properties>
+ <title>commons:contributing-md</title>
+ </properties>
+ <body>
+ <section name="commons:contributing-md">
+ <p><strong>Full name</strong>:</p>
+ <p>org.apache.commons:commons-build-plugin:1.5:contributing-md</p>
+ <p><strong>Description</strong>:</p>
+ <div>Commons Build Ant Mojo: Generate CONTRIBUTING.md</div>
+ <p><strong>Attributes</strong>:</p>
+ <ul>
+ <li>Requires a Maven 2.0 project to be executed.</li>
+ <li>Is NOT inherited by default in multi-project builds.</li>
+ </ul>
+ <subsection name="Required Parameters">
+ <table border="0" align="left">
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Since</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><strong><a href="#commons.jira.id">commons.jira.id</a></strong></td>
+ <td><code>String</code></td>
+ <td><code>-</code></td>
+ <td>The external JIRA id for the project (alphabetic, upper case)<br/><strong>Default value is</strong>: <code>${commons.jira.id}</code>.</td>
+ </tr>
+ <tr>
+ <td><strong><a href="#basedir">basedir</a></strong></td>
+ <td><code>File</code></td>
+ <td><code>-</code></td>
+ <td>The base directory from which to execute the Ant script.<br/><strong>Default value is</strong>: <code>${basedir}</code>.</td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="Optional Parameters">
+ <table border="0" align="left">
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Since</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><strong><a href="#messageLevel">messageLevel</a></strong></td>
+ <td><code>String</code></td>
+ <td><code>-</code></td>
+ <td>The message-level used to tune the verbosity of Ant logging.<br/><strong>Default value is</strong>: <code>info</code>.</td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="Parameter Details">
+ <p><strong><a name="commons.jira.id">commons.jira.id</a>:</strong></p>
+ <div>The external JIRA id for the project (alphabetic, upper case)</div>
+ <ul>
+ <li><strong>Type</strong>: <code>java.lang.String</code></li>
+ <li><strong>Required</strong>: <code>Yes</code></li>
+ <li><strong>Default</strong>: <code>${commons.jira.id}</code></li>
+ </ul><hr/><p><strong><a name="commons.jira.pid">commons.jira.pid</a>:</strong></p>
+ <div>The base directory from which to execute the Ant script.</div>
+ <ul>
+ <li><strong>Type</strong>: <code>java.io.File</code></li>
+ <li><strong>Required</strong>: <code>Yes</code></li>
+ <li><strong>Expression</strong>: <code>${antBasedir}</code></li>
+ <li><strong>Default</strong>: <code>${basedir}</code></li>
+ </ul><hr/><p><strong><a name="messageLevel">messageLevel</a>:</strong></p>
+ <div>The message-level used to tune the verbosity of Ant logging.</div>
+ <ul>
+ <li><strong>Type</strong>: <code>java.lang.String</code></li>
+ <li><strong>Required</strong>: <code>No</code></li>
+ <li><strong>Expression</strong>: <code>${antMessageLevel}</code></li>
+ <li><strong>Default</strong>: <code>info</code></li>
+ </ul>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md-mojo.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md.xml?rev=1620885&view=auto
==============================================================================
--- commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md.xml (added)
+++ commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md.xml Wed Aug 27 13:01:37 2014
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<!--
+ $HeadURL: https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md.xml $
+ $Revision: 1619060 $
+ -->
+<document>
+
+ <properties>
+ <title>Generating CONTRIBUTING.md</title>
+ <author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
+ </properties>
+
+ <body>
+
+
+ <section name="commons:contributing-md" href="contributing-md">
+
+ <subsection name="Overview">
+ <p>
+ The <code>commons:contributing-md</code> goal generates a CONTRIBUTING.md file for a component.
+ Execute the goal using the following command: <source>mvn commons:contributing-md</source>
+ </p>
+
+ <p>
+ <strong>Note:</strong> The CONTRIBUTING.md only needs to be generated once or if the template changes.
+ </p>
+
+ <p>
+ This goal uses the following:
+ <ul>
+ <li>The goal is mapped to the ant script/target using the <code>contributing-md</code> mojo defintion in the
+ <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml">generate-xdocs.mojos.xml</a> mapping document</li>
+ <li>Executes the <code>contributing-md</code> target in
+ <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml">generate-xdocs.build.xml</a>
+ ant script</li>
+ <li>Uses the <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/contributing-md-template.md">contributing-md-template.md</a>
+ template</li>
+ <li>Uses the <a href="contributing-md-mojo.html">goal's (i.e. mojo's) parameters</a> to filter values in the template</li>
+ </ul>
+ </p>
+ </subsection>
+
+ <subsection name="Configuration">
+ <p>
+ To generate a CONTRIBUTING.md, the following <a href="contributing-md-mojo.html">properties</a> are configured in the component's <code>pom.xml</code>
+ <ul>
+ <li><b>commons.jira.id</b> - JIRA's external (upper case) project id for the component</li>
+ </ul>
+ </p>
+ <p>
+ Example configuration for Commons Chain:
+<source><![CDATA[
+ <properties>
+ <commons.jira.id>CHAIN</commons.jira.id>
+ </properties>
+]]></source>
+ </p>
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
Propchange: commons/proper/commons-build-plugin/trunk/src/site/xdoc/contributing-md.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: commons/proper/commons-build-plugin/trunk/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-build-plugin/trunk/src/site/xdoc/index.xml?rev=1620885&r1=1620884&r2=1620885&view=diff
==============================================================================
--- commons/proper/commons-build-plugin/trunk/src/site/xdoc/index.xml (original)
+++ commons/proper/commons-build-plugin/trunk/src/site/xdoc/index.xml Wed Aug 27 13:01:37 2014
@@ -50,6 +50,7 @@
<li><a href="sandbox-jira-page.html">commons:sandbox-jira-page</a> - Generate a custom <i>JIRA Issue Tracking page</i> for a Sandbox component</li>
<li><a href="copy-javadoc-files-build.html">commons:copy-javadoc-files</a> - Copy NOTICE and LICENSE files to -javadoc jar</li>
<li><a href="readme-md.html">commons:readme-md</a> - Generate a README.md file containing information for contributors from GitHub</li>
+ <li><a href="contributing-md.html">commons:contributing-md</a> - Generate a CONTRIBUTING.md file containing information on how to contribute for contributors from GitHub</li>
</ul>
</p>
</section>