[SUBMIT] first pass at a task guidelines/process document.

Steve Loughran 4 Apr 2001 17:50:46 -0000

This is something I started in my spare time a couple of days ago, a better
document covering the process and the style for submitting new tasks and
patches to ant.


The checklists at the bottom are probably one of the key benefits -they list
what should be done for someone new to the process. I also cover the issues
of GPL licensing, test cases and documentation.

Where it is incomplete is

-needs more detail on helper classes, classes to extend from

-more on how to write ant tests (i.e. some simple examples for people that
dont know Junit)

-a list of what the recommended names for attributes and elements should be.

The latter kind of depends on ant2.0 and the proposal to unify naming
better. Should it be 'src' or 'source'? Will failonerror be an aspect or
something each task must write? These are still undecided issues. Maybe I
should just mention that these are still up in the air and just recommend
consistency with other tasks.

Comments? Contributions to where the doc is incomplete?

-steve

Title: Ant Task Design Guidelines

Ant Task Design Guidelines

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 writing tasks for personal use as the issues it addresses are still there in such a case.

Use built in helper classes

TODO: point to classes and code which are stable and intended to help tasks

Execute ...

Execute will spawn off separate programs under all the platforms which ant supports, dealing with java version sublties as well as platform issues. Always use this task to invoke other programs.

Java, ExecuteJava

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.

Project

Project has some helper functions to 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.

Good Tasks to Derive From

Task -for a simple task
MatchingTask -for pattern based tasks
Java -for code that invokes a new JVM

Obey the Sun/Java style guidelines

The Ant codebase aims to have a single unified coding standard, and that standard is the Sun Java coding guidelines

It's not that they are better than any alternatives, but they are a standard and they are what is consistently used in the rest of the tasks. Code will not be incorporated into the database until it complies with these.

If you are writing a task for your personal or organisational use, you are free to use whatever style you like. But using the Sun Java style will help you to become comfortable with the rest of the Ant source, which may be important.

Recommended Names for attributes and elements

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. TODO: list attribute/element names which should be standardised, and meaning failonerror, source, dest...

Design for controlled re-use

Keep member variables private. If read access by subclasses is required. add accessor methods rather than change the accessiblity of the member. This enables subclasses to access the contents, yet still be decoupled from the actual implementation.

The other common re-use mechanism in ant is for one task to create and configure another. This is fairly simple. (TODO: example)

Refactor

If the changes made to a task are making it too unwieldy, split it up into a cleaner design, refactor the code and submit not just feature creep but cleaner tasks. A common design pattern which tends to occur in the ant process is the adoption of the adapter pattern, in which a base class (say Javac or Rmi) starts off simple, then gets convoluted with support for multiple back ends -javac, jikes, jvc. A refactoring to split the programmable front end from the classes which provide the back end cleans up the design and makes it much easier to add new back ends. But to carry this off one needs to keep the interface and behaviour of the front end identical, and to be sure that no subclasses have been accessing data members directly -because these data members may not exist in the refactored design. Which is why having private data members is so important.

Test

Look in jakarta-ant/src/testcases 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.

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.

The test cases are a great way of testing your task during development. A simple call to 'ant test' in the ant source tree will run all ant tests, to verify that your changes dont break anything. You can also change to the directory containing the build files and just manually run ant against an individual build file and test case, which is often faster for tracking down a bug. Just make sure you are using the ant.jar you have just compiled.

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.

Document

Without documentation, the task can't be used. So remember to provide a succint and clear html (soon, xml) page describing the task in a similar style to that of existing tasks. It should include a list of attributes 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.

Licensing and Copyright

Any code submitted to the Apache project must be compatible with the Apache Software License, and the act of submission must be viewed as an implicit transfer of ownership of the submitted code to the Apache Software Foundation.

This is important.

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 commercial and closed source applications atop the Apache libraries and source -but not use the Apache, Ant or Jakarta Project names without permission.

Because the Gnu GPL license immediately extends to cover any larger application (or library, in the case of GLPL) into which it is incorporated, the Ant team can not incorporate any task based upon GPL or LGPL source into the Ant codebase. You are free to submit it, but it will be politely and firmly rejected.

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 CVS tree.

Dont re-invent the wheel

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 been submitted by someone else and not committed. You can avoid this by being aware of what is in the latest CVS tree -keep getting the daily source updates, look at manual changes and subscribe to the ant-dev mailing list.

Submitting to Ant

The process for submitting an ant task is documented on the jakarta web site. The basic mechanism is to mail it to the ant-dev mailing list. It helps to be on this list, as you will see other submissions, and any debate about your own submission.

Patches to existing files should be generated with cvs diff -u filename and save the output to a file. If you want to get the changes made to multiple files in a directory , just use cvs diff -u. The patches should be sent as an attachment to a message titled [PATCH] and distinctive one-line summary in the subject of the patch. The filename/task and the change usually suffices. Then you wait for one of the committers to commit the patch, if it is felt appropriate to do so. Bug fixes go in quickly, other changes often spark a bit of discussion before a (perhaps revised) commit is made.

New submissions should be proceeded with [SUBMIT]. The mailer-daemon will reject any messages over 100KB, so any large update should be zipped up.

Checklists

These are the things you should verify before submitting patches and new tasks. Things dont have to be perfect, it may take a couple of iterations before a patch or submission is committed, and these items can be addressed in the process. But by the time the code is committed, everything including the documentation and some test cases will have been done, so by getting them out the way up front can save time. Plus test cases are good way of getting your code to work and the documentation helps sell the reason for a task.

Checklist before submitting a patch

Added code complies with style guidelines
New member variables are private, and provide public accessor methods
Existing test cases succeed
New test cases written and succeed
Documentation page extended as appropriate
Example task declarations in the documentation tested.
Diff files generated using cvs diff -u
Message to ant-dev contains [PATCH], task name and patch reason in subject
Message body contains a rationale for the patch
Message body contains the patch file(s)

Checklist before submitting a new task

Java file begins with Apache copyright and license statement.
Task does not depend on GPL or LGPL code.
Source code complies with style guidelines
All member variables are private,
Maybe Task has failonerror attribute to control failure behaviour
New test cases written and succeed
Documentation page written
Example task declarations in the documentation tested.
Diff files generated using cvs diff -u
Message to ant-dev contains [SUBMIT] and task name in subject
Message body contains a rationale for the task
Message body contains the task files -source, documentation and test.