You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by ct...@snet.net on 2002/06/14 17:57:50 UTC
Re: cvs commit: jakarta-ant/docs ant_task_guidelines.html
I want off this list,
The moderator of this group SUCKS....
I have tried many Many MANY times to unsubscribe
Can anyone please tell me how to get off this list???
----- Original Message -----
From: <st...@apache.org>
To: <ja...@apache.org>
Sent: Monday, May 06, 2002 8:53 PM
Subject: cvs commit: jakarta-ant/docs ant_task_guidelines.html
> stevel 02/05/06 17:53:04
>
> Modified: docs Tag: ANT_15_BRANCH ant_task_guidelines.html
> Log:
> more stuff
>
> Revision Changes Path
> No revision
>
>
> No revision
>
>
> 1.5.2.1 +90 -14 jakarta-ant/docs/ant_task_guidelines.html
>
> Index: ant_task_guidelines.html
> ===================================================================
> RCS file: /home/cvs/jakarta-ant/docs/ant_task_guidelines.html,v
> retrieving revision 1.5
> retrieving revision 1.5.2.1
> diff -u -r1.5 -r1.5.2.1
> --- ant_task_guidelines.html 30 Oct 2001 10:05:32 -0000 1.5
> +++ ant_task_guidelines.html 7 May 2002 00:53:04 -0000 1.5.2.1
> @@ -12,6 +12,18 @@
> there in such a case.
>
>
> +<h2>Don't break existing builds</h2>
> +
> +Even if you find some really hideous problem with ant, one that is easy
> +to fix, if your fix breaks an existing build file then we have
problems.
> +Making sure that every build file out there still works, is one of the
> +goals of all changes. As an example of this, Ant1.5 passes the single
> +dollar sign "$" through in strings; Ant1.4 and before would strip it.
To
> +get this fix in we first had to write the test suite to expose current
> +behaviour, then change something so that singe $ was passed through,
but
> +double "$$" got mapped to "$" for backwards compatibility.
> +
> +
> <h2>Use built in helper classes</h2>
>
> Ant includes helper tasks to simplify mauch of your work. Be warned
that
> @@ -33,9 +45,10 @@
> classpath to be specified, and for forking to be an optional attribute.
>
>
> -<h4>Project</h4>
> +<h4>Project and related classes</h4>
>
> -Project has some helper functions to touch a file, to
> +Project, FileUtils, JavaEnvUtils all have helper functions
> +to do things like touch a file, to
> copy a file and the like. Use these instead of trying to code them
> yourself -or trying to use tasks which may be less stable and fiddlier
> to use.
> @@ -95,10 +108,41 @@
> destination directory for output
> </td>
> </tr>
> +<td>
> + destfile
> +</td>
> +<td>
> + destination file for output
> +</td>
> +</tr>
> +<tr>
> +<td>
> + srcdir
> +</td>
> +<td>
> + source directory
> +</td>
> +</tr>
> +<tr>
> +<td>
> + srcfile
> +</td>
> +<td>
> + source file
> +</td>
> +</tr>
> </table>
> Yes, this is a very short list. Try and be vaguely consistent with the
core
> tasks, at the very least.
>
> +<h2>Support classpaths</h2>
> +
> +Try and make it possible for people to supply a classpath to your task,
> +if you need external libraries, rather than make them add everything to
> +the ANT_HOME\lib directory. This lets people keep the external
libraries
> +in their ant-based project, rather than force all users to make changes
> +to their ant system configuration.
> +
> <h2>Design for controlled re-use</h2>
>
> Keep member variables private. If read access by subclasses is
required.
> @@ -188,23 +232,30 @@
> <p>
>
> The test cases are a great way of testing your task during development.
> -A simple call to 'ant run-test' in the ant source tree will run all ant
> +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 ${testname} is the name of your
test class.
> +-Dtestcase=${testname}</code> where <code>${testname}</code> is the
name of your test class.
>
>
> <p>
>
> The test cases are also used by the committers to verify that changes
> and patches do what they say. If you've got test cases it increases
your
> -credibility significantly.
> +credibility significantly. To be precise, we hate submissions without
> +test cases, as it means we have to write them ourselves. This is
> +something that only gets done if we need the task or it is perceived as
> +utterly essential to many users.
>
> <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.
> You can 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
> +accident.
>
> <h2>Document</h2>
>
> @@ -214,6 +265,11 @@
> and elements, and at least one working example of the task. Many users
> cut and paste the examples into their build files as a starting point,
> so make the examples practical and test them too.
> +<p>
> +You can use the xdocs stuff in proposal/xdocs to autogenerate your
> +documentation page from the javadocs of the source; this makes life
> +easier and will make the transition to a full xdoclet generated
> +documentation build process trivial.
>
> <h2>Licensing and Copyright</h2>
>
> @@ -229,11 +285,9 @@
>
> The fairly laissez-faire license of Apache is not compabitible with
> either the GPL or the Lesser GPL of the Free Software Foundation -the
> -Gnu project. Their license requires all changes to the source to be
made
> -public, and give the licensee of any software the right to distribute
> -copies. It also requires derivative works to be made available under
the
> -same license terms. None of these requirements are in the Apache
Software
> -Foundation license, which permits people and organisations to build
> +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.
> @@ -249,10 +303,25 @@
> <p>
>
> Once ant-2 adds better dynamic task incorporation, it may be possible
to
> -provide a framework for supporting [L]GPL code, but still no tasks
> -direcely subject to the Gnu licenses will ever be included in the Ant
> +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.
> +Tasks calling such code can use the 'exec' or 'java' tasks to run the
> +programs, as you are just executing them at this point, not linking to
> +them.
> +<p>
> +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.
> +
> +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>
>
> We've all done it: written and submitted a task only to discover it
> @@ -302,6 +371,13 @@
> into separate tasks.
> <p>
>
> +We also like submissions to be added to
> +<a href="http://nagoya.apache.org/bugzilla/">bugzilla</a>, so that they
> +dont get lost. Please submit them by first filing the report with a
> +meaningful name, then adding files as attachments. Use CVS diff files
> +please!
> +<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
> @@ -333,7 +409,7 @@
> <li>Message to ant-dev contains [PATCH], task name and patch reason in
> subject.
> <li>Message body contains a rationale for the patch.
> -<li>Message attachment contains the patch file(s).
> +<li>Message attachment contains the patch file(s).
> </ul>
>
> <h3>Checklist before submitting a new task</h3>
> @@ -356,7 +432,7 @@
> <li>Message to ant-dev contains [SUBMIT] and task name in subject
> <li>Message body contains a rationale for the task
> <li>Message attachments contain the required files -source,
documentation,
> -test and patches
> +test and patches zipped up to escape the HTML filter.
> </ul>
> <hr>
> <p align="center">Copyright © 2001 Apache Software Foundation. All
rights
>
>
>
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>