[dna-commits] DNA SVN: r711 - trunk/docs/reference/src/main/docbook/en-US/content.

[dna-commits at lists.jboss.org]

Author: rhauch
Date: 2009-01-15 22:26:56 -0500 (Thu, 15 Jan 2009)
New Revision: 711

Modified:
   trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml
Log:
DNA-273 Define and document the official patch procedure

Added a section to the 'Developer Tools' chapter in the Reference Guide to document the patch procedures.

Modified: trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml	2009-01-16 02:37:49 UTC (rev 710)
+++ trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml	2009-01-16 03:26:56 UTC (rev 711)
@@ -71,6 +71,23 @@
 			If you don't see the correct version, double-check your JDK installation.
 		</para>
 	</sect1>
+	<sect1 id="jira">
+		<title>JIRA</title>
+		<para>
+			JBoss DNA uses <ulink url="&JIRA;">JIRA</ulink> as its bug tracking, issue tracking, and project management tool.
+			This is a browser-based tool, with very good functionality for managing the different tasks.  It also serves as
+			the community's roadmap, since we can define new features and manage them along side the bugs and other issues.
+			Although most of the issues have been created by community members, we encourage any users to suggest new features,
+			log defects, or identify shortcomings in JBoss DNA.
+		</para>
+		<para>
+			The JBoss DNA community also encourages its members to work only issues that are managed in JIRA, and preferably those
+			that are targeted to the current release effort.  If something isn't in JIRA but needs to get done, then create an 
+			issue before you start working on the code changes.  Once you have code changes, you can upload a patch to the JIRA issue
+			if the change is complex, if you want someone to review it, or if you don't have commit privileges and have fixed
+			a bug.
+		</para>
+	</sect1>
 	<sect1 id="svn">
 		<title>Subversion</title>
 		<para>JBoss DNA uses Subversion as its source code management system, and specifically the instance at 
@@ -113,6 +130,37 @@
 				</tbody>
 			</tgroup>
 		</table>
+		<para>
+			When committing to SVN, be sure to include in a commit comment that includes the JIRA issue that the commit applies to and a very
+			good and thorough description of what was done.  It only takes a minute or two to be very clear about the change.  And including
+			the JIRA issue (e.g., "DNA-123") in the comment allows the JIRA system to track the changes that have been made for each issue.
+		</para>
+		<para>
+			Also, any single SVN commit should apply to one and only one JIRA issue.  Doing this helps ensure that each commit is atomic
+			and focused on a single activity.  There are exceptions to this rule, but they are rare.
+		</para>
+		<para>
+			Sometimes you may have some local changes that you don't want to (or aren't allowed to) commit.  You can make a patch file
+			and upload it to the JIRA issue, allowing other committers to review the patch.  However, to ensure that patches are easily
+			applied, please use SVN to create the patch.  To do this, simply do the following in the top of the codebase (e.g., the 
+			<code>trunk</code> directory):
+		</para>
+		<programlisting>$ svn diff . > ~/DNA-000.patch</programlisting> 
+		<para>
+			where <code>DNA-000</code> represents the DNA issue number.  Note that the above command places the patch file in your home directory,
+			but you can place the patch file anywhere.  Then, simply use JIRA to attach the patch file to the particular issue, also adding
+			a comment that describes the version number against which the patch was created.
+		</para>
+		<para>
+			To apply a patch, you usually want to start with a workspace that has no changes.  Download the patch file, then issue the
+			following command (again, from the top-level of the workspace):
+		</para>
+		<programlisting>$ patch -E -p0 &lt; ~/DNA-000.patch</programlisting> 
+		<para>
+			The "-E" option specifies to delete any files that were made empty by the application of the patch, and the "-p0" option instructs
+			the patch tool to not change any of the paths.  After you run this command, your working area should have the changes defined
+			by the patch.
+		</para>
 	</sect1>
 	<sect1 id="maven">
 		<title>Maven</title>