Revisiting of these. Some proofing; more on Java1.1 to 1.4 compatibility needs.

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@269792 13f79535-47bb-0310-9956-ffa450edef68

docs/ant_task_guidelines.html

@@ -7,7 +7,7 @@ Ant Task Design Guidelines
 <h1>Ant Task Design Guidelines</h1>
 
 This document covers how to write ant tasks to a standard required to be
-incorporated into the ant distribution. You may find it useful when
+incorporated into the Ant distribution. You may find it useful when
 writing tasks for personal use as the issues it addresses are still
 there in such a case.
 
@@ -22,13 +22,16 @@ development, maintenance and code size reasons.
 <h4>Execute</h4>
 
 Execute will spawn off separate programs under all the platforms which
-ant supports, dealing with java version sublties as well as platform
+ant supports, dealing with Java version issues as well as platform
 issues. Always use this task to invoke other programs. 
 
 <h4>Java, ExecuteJava</h4>
 
-These classes can be used to spawn java programs in a separate VM (they
+These classes can be used to spawn Java programs in a separate VM (they
 use execute) or in the same VM -with or without a different classloader. 
+When deriving tasks from this, it often benefits users to permit the 
+classpath to be specified, and for forking to be an optional attribute.
+
 
 <h4>Project</h4>
 
@@ -61,20 +64,40 @@ which may be important.
 
 <p>
 
-One controversial rule is 'no tabs'. Use four spaces instead. Not two,
+One important rule is 'no tabs'. Use four spaces instead. Not two,
 not eight, four. Even if your editor is configured to have a tab of four
 spaces, lots of others aren't -spaces have more consistency across
 editors and platforms.
 
 <h2>Recommended Names for attributes and elements</h2>
 
-The ant1.x tasks are fairly inconsistent regarding naming of attributes
--some tasks use source, others src. Here is a list of what is likely to
-be the preferred attribute names for ant 2.0. 
-
-<i>TODO: list attribute/element names which should be standardised, and meaning</i>
-
-failonerror, source, dest...
+The ant1.x tasks are very inconsistent regarding naming of attributes
+-some tasks use source, others src. Here is a list of preferred attribute
+names. 
+
+<table>
+<tr>
+<td>
+    failonerror
+</td>
+<td>
+    boolean to control whether failure to execute should throw a 
+    <tt>BuildException</tt> or just print an error.
+    Parameter validation failures should always throw an error, regardless
+    of this flag
+</td>
+</tr>
+<tr>
+<td>
+    destdir
+</td>
+<td>
+    destination directory for output
+</td>
+</tr>
+</table>
+Yes, this is a very short list. Try and be vaguely consistent with the core
+tasks, at the very least.
 
 <h2>Design for controlled re-use</h2>
 
@@ -85,7 +108,36 @@ still be decoupled from the actual implementation.
 <p>
 
 The other common re-use mechanism in ant is for one task to create and
-configure another. This is fairly simple. (TODO: example)
+configure another. This is fairly simple. 
+
+<h2>Support Java 1.1 through Java 1.4</h2>
+
+Ant is designed to support Java1.1: to build on it, to run on it. Sometimes
+functionality of tasks have to degrade in that environment -&lt;touch&gt;
+is a case in point- this is usually due to library limitations; 
+such behaviour change must always be noted in the documentation.
+<p>
+What is problematic is code which is dependent on Java1.2 features
+-Collections, Reader and Writer classes, extra methods in older classes.
+These can not be used directly by any code and still be able to compile
+and run on a Java 1.1 system. So please stick to the older collection
+classes, and the older IO classes. If a new method in an existing class
+is to be used, it must be used via reflection and the 
+<tt>NoSuchMethodException</tt> handled somehow. 
+<p>
+What if code simply does not work on Java1.1? It can happen. It will 
+probably be OK to have the task as an optional task, with compilation 
+restricted to Java1.2 or later through build.xml modifications. 
+Better still, use reflection to link to the classes at run time.
+<p>
+Java 1.4 adds a new optional change to the language itself, the 
+<tt>assert</tt> keyword, which is only enabled if the compiler is told
+to compile 1.4 version source. Clearly with the 1.1 compatibility requirement,
+Ant tasks can not use this keyword. They also need to move away from
+using the JUnit <tt>assert()</tt> method and start calling <tt>assertTrue()</tt>
+instead.    
+
+
 
 <h2>Refactor</h2>
 
@@ -106,14 +158,14 @@ is so important.
 
 <h2>Test</h2>
 
-Look in jakarta-ant/src/testcases and you will find Junit tests for the
+Look in <tt>jakarta-ant/src/testcases</tt> and you will find JUnit tests for the
 shipping ant tasks, to see how it is done and what is expected of a new
 task. Most of them are rudimentary, and no doubt you could do better for
 your task -feel free to do so!
 
 <p>
 
-A well written set of test cases will break the ant task while it is in
+A well written set of test cases will break the Ant task while it is in
 development, until the code is actually complete. And every bug which 
 surfaces later should have a test case added to demonstrate the problem,
 and to fix it.
@@ -135,11 +187,9 @@ credibility significantly.
 
 <p>
 
-Remember also that ant 1.x is designed to compile and run on Java1.1, so
-you should test on java 1.1 as well as any later version which you use.
-If you are developing on Windows you may well have the Microsoft JVM at
-hand for this, otherwise you can download an old SDK or runtime from
-Sun.
+Remember also that Ant 1.x is designed to compile and run on Java1.1, so
+you should test on Java 1.1 as well as any later version which you use.
+You can download an old SDK from Sun for this purpose.
 
 <h2>Document</h2>
 
@@ -207,7 +257,7 @@ line of code.
 
 <h2>Submitting to Ant</h2>
 
-The process for submitting an ant task is documented on the
+The process for submitting an Ant task is documented on the
 <a href="http://jakarta.apache.org/site/guidelines.html">
 jakarta web site</a>.
 The basic mechanism is to mail it to the ant-dev mailing list.
@@ -215,7 +265,8 @@ It helps to be on this list, as you will see other submissions, and
 any debate about your own submission.
 <p>
 
-Patches to existing files should be generated with <code>cvs diff -u filename</code>
+Patches to existing files should be generated with 
+<code>cvs diff -u filename</code>
  and save the output to a file. If you want to get
 the changes made to multiple files in a directory , just use <code>cvs
 diff -u</code>. The patches should be sent as an attachment to a message titled [PATCH]
@@ -234,7 +285,14 @@ New submissions should be proceeded with [SUBMIT]. The mailer-daemon
 will reject any messages over 100KB, so any large update should be
 zipped up. If your submission is bigger than that, why not break it up
 into separate tasks. 
+<p>
 
+If you hear nothing after a couple of weeks, remind the mailing list. 
+Sometimes really good submissions get lost in the noise of other issues.
+This is particularly the case just prior to a new point release of 
+the product. At that time anything other than bug fixes will tend
+to be neglected.
+ 
 <h2>Checklists</h2>
 
 These are the things you should verify before submitting patches and new
@@ -249,6 +307,7 @@ cases, while documentation helps sell the reason for a task.
 <h3>Checklist before submitting a patch</h3>
 <ul>
 <li>Added code complies with style guidelines
+<li>Code compiles and runs on Java1.1
 <li>New member variables are private, and provide public accessor methods
 	if access is actually needed. 
 <li>Existing test cases succeed.
@@ -267,6 +326,7 @@ subject.
 <li>Java file begins with Apache copyright and license statement.
 <li>Task does not depend on GPL or LGPL code.
 <li>Source code complies with style guidelines
+<li>Code compiles and runs on Java1.1
 <li>Member variables are private, and provide public accessor methods
 	if access is actually needed. 
 <li><i>Maybe</i> Task has failonerror attribute to control failure behaviour