stevel 2005/03/01 02:32:08
Modified: docs ant_task_guidelines.html
Log:
updated the guidelines
Revision Changes Path
1.14 +39 -17 ant/docs/ant_task_guidelines.html
Index: ant_task_guidelines.html
===================================================================
RCS file: /home/cvs/ant/docs/ant_task_guidelines.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- ant_task_guidelines.html 1 Jan 2005 20:27:34 -0000 1.13
+++ ant_task_guidelines.html 1 Mar 2005 10:32:08 -0000 1.14
@@ -23,6 +23,21 @@
behaviour, then change something so that singe $ was passed through, but
double "$$" got mapped to "$" for backwards compatibility.
+<h2>Don't break the Java API</h2>
+
+Ant's tasks can be used by third party programs, and by third party tasks.
+We cannot make changes that break the API. This includes
+<ol>
+<li>Moving classes without leaving a backwards-compatible facade.
+<li>Deleting classes.
+<li>Deleting methods or fields, or reducing their accessibility.
+<li>Changing the signature of a <tt>setAttribute(Type)</tt> method. If you
need
+to add a restrictive type, add a new attribute, and place it in the source
+<i>above</i> the original. The XML mapper will get the restricted type, old
programs
+can still use the old type.
+<li>Don't change semantics. At least, not drastically. All bug fixes are
+implicit changes of semantics, after all.
+</ol>
<h2>Use built in helper classes</h2>
@@ -180,7 +195,7 @@
they can, because their needless work can trickle through the entire build,
test
and deploy process.
-<h2>Support Java 1.2 through Java 1.4</h2>
+<h2>Support Java 1.2 through Java 1.5+</h2>
Ant1.5 and lower was designed to support Java1.1. Ant1.6 and higher
is designed to support Java1.2: to build on it, to run on it. Sometimes
@@ -210,9 +225,14 @@
using the JUnit <tt>assert()</tt> method and call <tt>assertTrue()</tt>
instead.
<p>
-Java 1.5 will (perhaps) add a new keyword - enum, one should avoid
-this for future compatibility.
+Java 1.5 adds the <tt>enum</tt>; again, this must not be used.
+
+<h2>Explicitly Expand properties in nested text</h2>
+For historical reasons, <tt>addText(String text)</tt> is called to
+set the task's nested text, without any property expansion taking place.
+Call <tt>Project.replaceProperties()</tt> to do this manually.
+
<h2>Refactor</h2>
@@ -230,6 +250,13 @@
exist in the refactored design. Which is why having private data members
is so important.
+<p>
+
+One thing we can not do is move existing tasks around or delete them.
+Remember that Ant has a Java API as well as an XML language. We don't want
+to break that API, or anything that subclasses existing Ant tasks. When
+refactoring, you need to leave facades where the original classes were. so
+existing code does not break.
<h2>Test</h2>
@@ -251,7 +278,8 @@
A simple call to 'build run-test' in the ant source tree will run all ant
tests, to verify that your changes don't break anything.
To test a single task, use the one shot <code>ant run-single-test
--Dtestcase=${testname}</code> where <code>${testname}</code> is the name of
your test class.
+-Dtestcase=${testname}</code> where <code>${testname}</code>
+is the name of your test class.
<p>
@@ -267,7 +295,7 @@
Remember also that Ant 1.x is designed to compile and run on Java1.2, so
you should test on Java 1.2 as well as any later version which you use.
-You can download an old SDK from Sun for this purpose.
+You ought to be able to download an old SDK from Sun for this purpose.
<p>
Finally, run a full <code>build test</code> before and after you start
developing your project, to make sure you havent broken anything else by
@@ -299,14 +327,14 @@
<p>
-The fairly laissez-faire license of Apache is not compabitible with
+The fairly laissez-faire license of Apache is not currently considered
+compabitible with
either the GPL or the Lesser GPL of the Free Software Foundation -the
Gnu project. These licenses have stricter terms, "copyleft", which are
not in the Apache Software Foundation license.
This permits people and organisations to build
commercial and closed source applications atop the Apache libraries and
-source -but not use the Apache, Ant or Jakarta Project names without
-permission.
+source.
<p>
@@ -317,13 +345,6 @@
will be politely and firmly rejected.
<p>
-
-Once ant-2 adds better dynamic task incorporation, it may be possible to
-provide a framework for indirectly supporting [L]GPL code, but still no tasks
-directly subject to the Gnu licenses can be included in the Ant
-CVS tree.
-
-<p>
If you link to a GPL or LGPL library, by <code>import</code> or
reflection, your task must be licensed under the same terms. So tasks
linking to (L)GPL code can't go into the Apache managed codebase.
@@ -334,11 +355,12 @@
Even if we cannot include your task into the Apache codebase, we can
still point to where you host it -just submit a diff to
xdocs/external.html pointing to your task.
-
+<p>
If your task links directly to proprietary code, we have a differnt
problem: it is really hard to build the tasks. Please use reflection.
-<h3>Dont re-invent the wheel</h3>
+
+<h3>Don't re-invent the wheel</h3>
We've all done it: written and submitted a task only to discover it
was already implemented in a small corner of another task, or it has
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
