1 | <!--
|
---|
2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
---|
3 | contributor license agreements. See the NOTICE file distributed with
|
---|
4 | this work for additional information regarding copyright ownership.
|
---|
5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
---|
6 | (the "License"); you may not use this file except in compliance with
|
---|
7 | the License. You may obtain a copy of the License at
|
---|
8 |
|
---|
9 | http://www.apache.org/licenses/LICENSE-2.0
|
---|
10 |
|
---|
11 | Unless required by applicable law or agreed to in writing, software
|
---|
12 | distributed under the License is distributed on an "AS IS" BASIS,
|
---|
13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
14 | See the License for the specific language governing permissions and
|
---|
15 | limitations under the License.
|
---|
16 | -->
|
---|
17 | <html><head>
|
---|
18 | <title>
|
---|
19 | Apache Ant Task Design Guidelines
|
---|
20 | </title>
|
---|
21 | </head><body>
|
---|
22 |
|
---|
23 | <h1>Apache Ant Task Design Guidelines</h1>
|
---|
24 |
|
---|
25 | This document covers how to write Ant tasks to a standard required to be
|
---|
26 | incorporated into the Ant distribution. You may find it useful when
|
---|
27 | writing tasks for personal use as the issues it addresses are still
|
---|
28 | there in such a case.
|
---|
29 |
|
---|
30 | <h2>Don't break existing builds</h2>
|
---|
31 |
|
---|
32 | Even if you find some really hideous problem with Ant, one that is easy to fix,
|
---|
33 | if your fix breaks an existing build file then we have problems. Making sure
|
---|
34 | that every build file out there still works is one of the goals of all changes.
|
---|
35 | As an example of this, Ant 1.5 passes the single dollar sign "$"
|
---|
36 | through in strings; Ant 1.4 and before would strip it. To get this fix in we
|
---|
37 | first had to write the test suite to expose current behaviour, then change
|
---|
38 | something so that single "$" was passed through, but double
|
---|
39 | "$$" got mapped to "$" for backwards compatibility.
|
---|
40 |
|
---|
41 | <h2>Don't break the Java API</h2>
|
---|
42 |
|
---|
43 | Ant's tasks can be used by third party programs and tasks.
|
---|
44 | We cannot make changes that break the API. This includes:
|
---|
45 | <ol>
|
---|
46 | <li>Moving classes without leaving a backwards-compatible facade.
|
---|
47 | <li>Deleting classes.
|
---|
48 | <li>Deleting methods or fields, or reducing their accessibility.
|
---|
49 | <li>Changing the signature of a <tt>setAttribute(Type)</tt> method. If you need
|
---|
50 | to add a restrictive type, add a new attribute, and place it in the source
|
---|
51 | <i>above</i> the original. The XML mapper will get the restricted type, old programs
|
---|
52 | can still use the old type.
|
---|
53 | <li>Don't change semantics. At least, not drastically. All bug fixes are
|
---|
54 | implicit changes of semantics, after all.
|
---|
55 | </ol>
|
---|
56 |
|
---|
57 | <h2>Use built in helper classes</h2>
|
---|
58 |
|
---|
59 | Ant includes helper tasks to simplify much of your work. It is much better to
|
---|
60 | use them than roll your own, for development, maintenance and code size reasons.
|
---|
61 |
|
---|
62 | <h4>Execute</h4>
|
---|
63 |
|
---|
64 | Execute will spawn off separate programs under all the platforms which
|
---|
65 | Ant supports, dealing with Java version issues as well as platform
|
---|
66 | issues. Always use this class to invoke other programs.
|
---|
67 |
|
---|
68 | <h4>Java, ExecuteJava</h4>
|
---|
69 |
|
---|
70 | These classes can be used to spawn Java programs in a separate VM (they
|
---|
71 | use execute) or in the same VM--with or without a different classloader.
|
---|
72 | When deriving tasks from this, it often benefits users to permit the
|
---|
73 | classpath to be specified, and for forking to be an optional attribute.
|
---|
74 |
|
---|
75 | <h4>Project and related classes</h4>
|
---|
76 |
|
---|
77 | Project, FileUtils, JavaEnvUtils all have helper functions to do things like
|
---|
78 | touch a file, copy a file and the like. Use these instead of coding them
|
---|
79 | yourself or trying to use tasks which may be less stable and fiddlier to use.
|
---|
80 |
|
---|
81 | <h2>Obey the Sun/Java style guidelines</h2>
|
---|
82 |
|
---|
83 | The Ant codebase aims to have a single unified coding standard, and that
|
---|
84 | standard is the
|
---|
85 | <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">
|
---|
86 | Sun Java coding guidelines
|
---|
87 | </a>
|
---|
88 | <p>
|
---|
89 |
|
---|
90 | It's not that they are better than any alternatives, but they are a
|
---|
91 | standard and they are what is consistently used in the rest of the
|
---|
92 | tasks. Code will not be incorporated into the database until it complies
|
---|
93 | with these.
|
---|
94 |
|
---|
95 | <p>
|
---|
96 |
|
---|
97 | If you are writing a task for your personal or organisational use, you
|
---|
98 | are free to use whatever style you like. But using the Sun Java style
|
---|
99 | will help you to become comfortable with the rest of the Ant source,
|
---|
100 | which may be important.
|
---|
101 |
|
---|
102 | <p>
|
---|
103 |
|
---|
104 | One important rule is 'no tabs'. Use four spaces instead. Not two,
|
---|
105 | not eight, four. Even if your editor is configured to have a tab of four
|
---|
106 | spaces, lots of others aren't. Spaces have more consistency across
|
---|
107 | editors and platforms. Some IDEs (JEdit) can highlight tabs, to stop you
|
---|
108 | accidentally inserting them.
|
---|
109 | <p>
|
---|
110 | There is an Ant build file check.xml in the main ant directory with runs
|
---|
111 | <a href="http://checkstyle.sourceforge.net">checkstyle</a> over
|
---|
112 | Ant's source code.
|
---|
113 |
|
---|
114 | <h2>Attributes and elements</h2>
|
---|
115 | Use the Ant introspection-based mapping of attributes into Java datatypes,
|
---|
116 | rather than implementing all your attributes as setFoo(String) and doing
|
---|
117 | the mapping to int, boolean or File yourself. This saves work on your part,
|
---|
118 | lets Java callers use you in a typesafe manner, and will let the Xdocs
|
---|
119 | documentation generator work out what the parameters are.
|
---|
120 |
|
---|
121 | <p>
|
---|
122 | The Ant 1.x tasks are very inconsistent regarding naming of attributes--some
|
---|
123 | tasks use <tt>source</tt>, others <tt>src</tt>.
|
---|
124 | Here is a list of preferred attribute names:
|
---|
125 | <p>
|
---|
126 | <table cellpadding="5">
|
---|
127 | <tr>
|
---|
128 | <td>
|
---|
129 | failonerror
|
---|
130 | </td>
|
---|
131 | <td>
|
---|
132 | boolean to control whether failure to execute should throw a
|
---|
133 | <tt>BuildException</tt> or just print an error.
|
---|
134 | Parameter validation failures should always throw an error, regardless
|
---|
135 | of this flag.
|
---|
136 | </td>
|
---|
137 | </tr>
|
---|
138 | <tr>
|
---|
139 | <td>
|
---|
140 | destdir
|
---|
141 | </td>
|
---|
142 | <td>
|
---|
143 | destination directory for output
|
---|
144 | </td>
|
---|
145 | </tr>
|
---|
146 | <tr>
|
---|
147 | <td>
|
---|
148 | destfile
|
---|
149 | </td>
|
---|
150 | <td>
|
---|
151 | destination file for output
|
---|
152 | </td>
|
---|
153 | </tr>
|
---|
154 | <tr>
|
---|
155 | <td>
|
---|
156 | srcdir
|
---|
157 | </td>
|
---|
158 | <td>
|
---|
159 | source directory
|
---|
160 | </td>
|
---|
161 | </tr>
|
---|
162 | <tr>
|
---|
163 | <td>
|
---|
164 | srcfile
|
---|
165 | </td>
|
---|
166 | <td>
|
---|
167 | source file
|
---|
168 | </td>
|
---|
169 | </tr>
|
---|
170 | </table>
|
---|
171 | <p>
|
---|
172 | Yes, this is a very short list. Try and be vaguely consistent with the core
|
---|
173 | tasks, at the very least.
|
---|
174 |
|
---|
175 | <h2>Support classpaths</h2>
|
---|
176 |
|
---|
177 | Try and make it possible for people to supply a classpath to your task,
|
---|
178 | if you need external libraries, rather than make them add everything to
|
---|
179 | the ANT_HOME/lib directory. This lets people keep the external libraries
|
---|
180 | in their Ant-based project, rather than force all users to make changes
|
---|
181 | to their Ant system configuration.
|
---|
182 |
|
---|
183 | <h2>Design for controlled re-use</h2>
|
---|
184 |
|
---|
185 | Keep member variables private. If read access by subclasses is required,
|
---|
186 | add accessor methods rather than change the accessiblity of the member.
|
---|
187 | This enables subclasses to access the contents, yet still be decoupled
|
---|
188 | from the actual implementation.
|
---|
189 | <p>
|
---|
190 |
|
---|
191 | The other common re-use mechanism in Ant is for one task to create and
|
---|
192 | configure another. This is fairly simple. There are facilities available in
|
---|
193 | Ant's API to have the tasks instantiated by their familiar names
|
---|
194 | ("java", "exec", etc.). It is recommended that you
|
---|
195 | <b>not</b> use this approach because of the entirely real possibility that a
|
---|
196 | user has overridden the name to point to a different class entirely. Use direct
|
---|
197 | constructor calls (or reflection) to instantiate your subtask. Since Ant 1.6.3,
|
---|
198 | you can call <code>org.apache.tools.ant.Task#bindToOwner()</code>
|
---|
199 | to "mask" a helper task as its parent.
|
---|
200 |
|
---|
201 | <h2>Do your own Dependency Checking</h2>
|
---|
202 |
|
---|
203 | Make has the edge over Ant in its integrated dependency checking; the
|
---|
204 | command line apps make invokes don't need to do their own work. Ant tasks
|
---|
205 | do have to do their own dependency work, but if this can be done then
|
---|
206 | it can be done well. A good dependency-aware task can work out the dependencies
|
---|
207 | without explicit dependency information in the build file, and be smart
|
---|
208 | enough to work out the real dependencies, perhaps through a bit of file parsing.
|
---|
209 | The <tt>depends</tt> task is the best example of this. Some of the zip/jar
|
---|
210 | tasks are pretty good too, as they can update the archive when needed.
|
---|
211 | Most tasks just compare source and destination timestamps and work from there.
|
---|
212 | Tasks which don't do any dependency checking do not help users as much as
|
---|
213 | they can, because their needless work can trickle through the entire build, test
|
---|
214 | and deploy process.
|
---|
215 |
|
---|
216 | <h2>Support Java 1.2 through Java 1.5+</h2>
|
---|
217 |
|
---|
218 | Ant 1.5 and lower was designed to support Java 1.1. Ant 1.6 and higher
|
---|
219 | is designed to support Java 1.2: to build on it, to run on it. Sometimes
|
---|
220 | functionality of tasks have to degrade in that environment--usually due to
|
---|
221 | library limitations; such behaviour change must always be noted in the
|
---|
222 | documentation.
|
---|
223 | <p>
|
---|
224 | What is problematic is code which is dependent on Java 1.3 features;
|
---|
225 | e.g. java.lang.reflect.Proxy, or Java 1.4 features; e.g. java.io.nio.
|
---|
226 | Be also aware of extra methods in older classes;
|
---|
227 | e.g. StringBuffer#append(StringBuffer). These cannot be used directly
|
---|
228 | by any code and still be able to compile and run on a Java 1.2 system.
|
---|
229 | If a new method in an existing class is to be used, it must be used via
|
---|
230 | reflection and the <tt>NoSuchMethodException</tt> handled somehow.
|
---|
231 | <p>
|
---|
232 | What if code simply does not work on Java 1.2? It can happen. It will
|
---|
233 | probably be OK to have the task as an optional task, with compilation
|
---|
234 | restricted to Java 1.3 or later through build.xml modifications.
|
---|
235 | Better still, use reflection to link to the classes at run time.
|
---|
236 | <p>
|
---|
237 | Java 1.4 adds a new optional change to the language itself, the
|
---|
238 | <tt>assert</tt> keyword, which is only enabled if the compiler is told
|
---|
239 | to compile 1.4 version source. Clearly with the 1.2 compatibility requirement,
|
---|
240 | Ant tasks cannot use this keyword. They also need to move away from
|
---|
241 | using the JUnit <tt>assert()</tt> method and call <tt>assertTrue()</tt>
|
---|
242 | instead.
|
---|
243 | <p>
|
---|
244 | Java 1.5 adds the <tt>enum</tt> type; again, this must not be used.
|
---|
245 |
|
---|
246 | <h2>Explicitly Expand properties in nested text</h2>
|
---|
247 |
|
---|
248 | For historical reasons, <tt>addText(String text)</tt> is called to
|
---|
249 | set the task's nested text, without any property expansion taking place.
|
---|
250 | Call <tt>Project.replaceProperties()</tt> to do this manually.
|
---|
251 | If you forget, you create a problem that is impossible to fix
|
---|
252 | without breaking users' build files.
|
---|
253 |
|
---|
254 | <h2>Refactor</h2>
|
---|
255 |
|
---|
256 | If the changes made to a task are making it too unwieldy, split it up
|
---|
257 | into a cleaner design, refactor the code and submit not just feature
|
---|
258 | creep but cleaner tasks. A common design pattern which tends to occur in
|
---|
259 | the Ant process is the adoption of the adapter pattern, in which a base
|
---|
260 | class (say Javac or Rmic) starts off simply, then gets convoluted with
|
---|
261 | support for multiple back ends: javac, jikes, jvc. A refactoring to
|
---|
262 | split the programmable front end from the classes which provide the back
|
---|
263 | end cleans up the design and makes it much easier to add new back ends.
|
---|
264 | But to carry this off one needs to keep the interface and behaviour of
|
---|
265 | the front end identical, and to be sure that no subclasses have been
|
---|
266 | accessing data members directly, because these data members may not
|
---|
267 | exist in the refactored design. This is why having private data members
|
---|
268 | is so important.
|
---|
269 |
|
---|
270 | <p>
|
---|
271 |
|
---|
272 | One thing we must not do is move existing tasks around or delete them.
|
---|
273 | Remember that Ant has a Java API as well as an XML language. We don't want
|
---|
274 | to break that API, or anything that subclasses existing Ant tasks. When
|
---|
275 | refactoring, you need to leave facades where the original classes were. so
|
---|
276 | existing code does not break.
|
---|
277 |
|
---|
278 | <h2>Test</h2>
|
---|
279 |
|
---|
280 | Look in <tt>ant/src/testcases</tt> and you will find JUnit tests for the
|
---|
281 | shipping Ant tasks, to see how it is done and what is expected of a new
|
---|
282 | task. Most of them are rudimentary, and no doubt you could do better for
|
---|
283 | your task--feel free to do so!
|
---|
284 |
|
---|
285 | <p>
|
---|
286 |
|
---|
287 | A well written set of test cases will break the Ant task while it is in
|
---|
288 | development, until the code is actually complete. And every bug which
|
---|
289 | surfaces later should have a test case added to demonstrate the problem,
|
---|
290 | and to fix it.
|
---|
291 |
|
---|
292 | <p>
|
---|
293 |
|
---|
294 | The test cases are a great way of testing your task during development.
|
---|
295 | A simple call to 'build run-test' in the ant source tree will run all ant
|
---|
296 | tests, to verify that your changes don't break anything.
|
---|
297 | To test a single task, use the one shot <code>ant run-single-test
|
---|
298 | -Dtestcase=${testname}</code> where <code>${testname}</code>
|
---|
299 | is the name of your test class.
|
---|
300 |
|
---|
301 | <p>
|
---|
302 |
|
---|
303 | The test cases are also used by the committers to verify that changes
|
---|
304 | and patches do what they say. If you've got test cases it increases your
|
---|
305 | credibility significantly. To be precise, we hate submissions without
|
---|
306 | test cases, as it means we have to write them ourselves. This is
|
---|
307 | something that only gets done if we need the task or it is perceived as
|
---|
308 | utterly essential to many users.
|
---|
309 |
|
---|
310 | <p>
|
---|
311 |
|
---|
312 | Remember also that Ant 1.x is designed to compile and run on Java 1.2, so
|
---|
313 | you should test on Java 1.2 as well as any later version which you use.
|
---|
314 | You ought to be able to download an old SDK from Sun for this purpose.
|
---|
315 | <p>
|
---|
316 | Finally, run a full <code>build test</code> before and after you start
|
---|
317 | developing your project, to make sure you haven't broken anything else by
|
---|
318 | accident.
|
---|
319 |
|
---|
320 | <h2>Document</h2>
|
---|
321 |
|
---|
322 | Without documentation, the task can't be used. So remember to provide a
|
---|
323 | succinct and clear html (soon, xml) page describing the task in a similar
|
---|
324 | style to that of existing tasks. It should include a list of attributes
|
---|
325 | and elements, and at least one working example of the task. Many users
|
---|
326 | cut and paste the examples into their build files as a starting point,
|
---|
327 | so make the examples practical and test them too.
|
---|
328 | <p>
|
---|
329 | You can use the xdocs stuff in proposal/xdocs to autogenerate your
|
---|
330 | documentation page from the javadocs of the source; this makes life
|
---|
331 | easier and will make the transition to a full xdoclet generated
|
---|
332 | documentation build process trivial.
|
---|
333 |
|
---|
334 | <h2>Licensing and Copyright</h2>
|
---|
335 |
|
---|
336 | Any code submitted to the Apache project must be compatible with the
|
---|
337 | Apache Software License, and the act of submission must be viewed as
|
---|
338 | an implicit license of the submitted code to the Apache Software
|
---|
339 | Foundation.
|
---|
340 |
|
---|
341 | <p>
|
---|
342 | This is important.
|
---|
343 |
|
---|
344 | <p>
|
---|
345 |
|
---|
346 | The fairly laissez-faire license of Apache is not currently considered
|
---|
347 | compatible with
|
---|
348 | either the GPL or the Lesser GPL of the Free Software Foundation--the
|
---|
349 | Gnu project. These licenses have stricter terms, "copyleft",
|
---|
350 | which are not in the Apache Software Foundation license.
|
---|
351 | This permits people and organisations to build
|
---|
352 | commercial and closed source applications atop the Apache libraries and source.
|
---|
353 |
|
---|
354 | <p>
|
---|
355 |
|
---|
356 | Because the Gnu GPL license immediately extends to cover any larger
|
---|
357 | application (or library, in the case of LGPL) into which it is
|
---|
358 | incorporated, the Ant team cannot incorporate any task based upon GPL
|
---|
359 | or LGPL source into the Ant codebase. You are free to submit it, but it
|
---|
360 | will be politely and firmly rejected.
|
---|
361 |
|
---|
362 | <p>
|
---|
363 | If you link to a GPL or LGPL library, by <code>import</code> or
|
---|
364 | reflection, your task must be licensed under the same terms. So tasks
|
---|
365 | linking to (L)GPL code can't go into the Apache managed codebase.
|
---|
366 | Tasks calling such code can use the 'exec' or 'java' tasks to run the
|
---|
367 | programs, as you are just executing them at this point, not linking to
|
---|
368 | them.
|
---|
369 | <p>
|
---|
370 | Even if we cannot include your task into the Apache codebase, we can
|
---|
371 | still point to where you host it; just submit a diff to
|
---|
372 | xdocs/external.html pointing to your task.
|
---|
373 | <p>
|
---|
374 | If your task links directly to proprietary code, we have a different
|
---|
375 | problem: it is really hard to build the tasks. Please use reflection.
|
---|
376 |
|
---|
377 | <h3>Don't re-invent the wheel</h3>
|
---|
378 |
|
---|
379 | We've all done it: written and submitted a task only to discover it
|
---|
380 | was already implemented in a small corner of another task, or it has
|
---|
381 | been submitted by someone else and not committed. You can avoid this
|
---|
382 | by being aware of what is in the latest CVS tree; keep getting the daily
|
---|
383 | source updates, look at manual changes and subscribe to the dev
|
---|
384 | mailing list.
|
---|
385 |
|
---|
386 | <p>
|
---|
387 |
|
---|
388 | If you are thinking of writing a task, posting a note on your thoughts
|
---|
389 | to the list can be informative--you will get other peoples' insights and
|
---|
390 | maybe some half-written task to do the basics, all without writing a
|
---|
391 | line of code.
|
---|
392 |
|
---|
393 | <h2>Submitting to Ant</h2>
|
---|
394 |
|
---|
395 | The basic mechanism for submitting an Ant task is to mail it to the
|
---|
396 | dev mailing list. It helps to be on this list, as you will see other
|
---|
397 | submissions, and any debate about your own submission.
|
---|
398 | <p>
|
---|
399 | You may create your patch file using either of the following approaches
|
---|
400 | (the committers recommend the first):
|
---|
401 | <p>
|
---|
402 | <ul>
|
---|
403 | <li><h3>Approach 1 - The Ant Way</h3>
|
---|
404 | <p>
|
---|
405 | Use Ant to generate a patch file to Ant:
|
---|
406 | <pre class="code">
|
---|
407 | ant -f patch.xml
|
---|
408 | </pre>
|
---|
409 | This will create a file named patch.tar.gz that will contain a unified
|
---|
410 | diff of files that have been modified and also include files that have
|
---|
411 | been added. Review the file for completeness and correctness. This approach
|
---|
412 | is recommended because it standardizes the way in which patch files are
|
---|
413 | constructed. It also eliminates the chance of you missing to submit new files
|
---|
414 | that constitute part of the patch.
|
---|
415 | <p>
|
---|
416 | <li><h3>Approach 2 - The Manual Way</h3>
|
---|
417 | <p>
|
---|
418 | Patches to existing files should be generated with
|
---|
419 | <code>svn diff -u filename</code>
|
---|
420 | and save the output to a file. If you want to get
|
---|
421 | the changes made to multiple files in a directory , just use <code>cvs
|
---|
422 | diff -u</code>. Then, Tar and GZip the patch file as well as any new files
|
---|
423 | that you have added.
|
---|
424 | </ul>
|
---|
425 | <p>
|
---|
426 | The patches should be sent as an attachment to a message titled [PATCH]
|
---|
427 | and distinctive one-line summary in the subject of the patch. The
|
---|
428 | filename/task and the change usually suffices. It's important to include
|
---|
429 | the changes as an attachment, as too many mailers reformat the text
|
---|
430 | pasted in, which breaks the patch.
|
---|
431 | <p>
|
---|
432 | Then you wait for one of the committers to commit the patch, if it is
|
---|
433 | felt appropriate to do so. Bug fixes go in quickly, other changes
|
---|
434 | often spark a bit of discussion before a (perhaps revised) commit is
|
---|
435 | made.
|
---|
436 | <p>
|
---|
437 |
|
---|
438 | New submissions should be proceeded with [SUBMIT]. The mailer-daemon
|
---|
439 | will reject any messages over 100KB, so any large update should be
|
---|
440 | zipped up. If your submission is bigger than that, why not break it up
|
---|
441 | into separate tasks.
|
---|
442 | <p>
|
---|
443 |
|
---|
444 | We also like submissions to be added to
|
---|
445 | <a href="http://issues.apache.org/bugzilla/">bugzilla</a>, so that they dont get lost. Please submit them by first filing the report with a
|
---|
446 | meaningful name, then adding files as attachments. Use CVS diff files
|
---|
447 | please!
|
---|
448 | <p>
|
---|
449 |
|
---|
450 | If you hear nothing after a couple of weeks, remind the mailing list.
|
---|
451 | Sometimes really good submissions get lost in the noise of other issues.
|
---|
452 | This is particularly the case just prior to a new point release of
|
---|
453 | the product. At that time anything other than bug fixes will tend
|
---|
454 | to be neglected.
|
---|
455 |
|
---|
456 | <h2>Checklists</h2>
|
---|
457 |
|
---|
458 | These are the things you should verify before submitting patches and new
|
---|
459 | tasks. Things don't have to be perfect; it may take a couple of
|
---|
460 | iterations before a patch or submission is committed, and these items
|
---|
461 | can be addressed in the process. But by the time the code is committed,
|
---|
462 | everything including the documentation and some test cases will have
|
---|
463 | been done, so getting them out the way up front can save time.
|
---|
464 | The committers look more favourably on patches and submissions with test
|
---|
465 | cases, while documentation helps sell the reason for a task.
|
---|
466 |
|
---|
467 | <h3>Checklist before submitting a patch</h3>
|
---|
468 | <ul>
|
---|
469 | <li>Added code complies with style guidelines
|
---|
470 | <li>Code compiles and runs on Java 1.2
|
---|
471 | <li>New member variables are private, and provide public accessor methods
|
---|
472 | if access is actually needed.
|
---|
473 | <li>Existing test cases succeed.
|
---|
474 | <li>New test cases written and succeed.
|
---|
475 | <li>Documentation page extended as appropriate.
|
---|
476 | <li>Example task declarations in the documentation tested.
|
---|
477 | <li>Diff files generated using svn diff -u
|
---|
478 | <li>Message to dev contains [PATCH], task name and patch reason in
|
---|
479 | subject.
|
---|
480 | <li>Message body contains a rationale for the patch.
|
---|
481 | <li>Message attachment contains the patch file(s).
|
---|
482 | </ul>
|
---|
483 |
|
---|
484 | <h3>Checklist before submitting a new task</h3>
|
---|
485 | <ul>
|
---|
486 | <li>Java file begins with Apache copyright and license statement.
|
---|
487 | <li>Task does not depend on GPL or LGPL code.
|
---|
488 | <li>Source code complies with style guidelines
|
---|
489 | <li>Code compiles and runs on Java 1.2
|
---|
490 | <li>Member variables are private, and provide public accessor methods
|
---|
491 | if access is actually needed.
|
---|
492 | <li><i>Maybe</i> Task has failonerror attribute to control failure behaviour
|
---|
493 | <li>New test cases written and succeed
|
---|
494 | <li>Documentation page written
|
---|
495 | <li>Example task declarations in the documentation tested.
|
---|
496 | <li>Patch files generated using svn diff -u
|
---|
497 | <li>patch files include a patch to defaults.properties to register the
|
---|
498 | tasks
|
---|
499 | <li>patch files include a patch to coretasklist.html or
|
---|
500 | optionaltasklist.html to link to the new task page
|
---|
501 | <li>Message to dev contains [SUBMIT] and task name in subject
|
---|
502 | <li>Message body contains a rationale for the task
|
---|
503 | <li>Message attachments contain the required files -source, documentation,
|
---|
504 | test and patches zipped up to escape the HTML filter.
|
---|
505 | </ul>
|
---|
506 |
|
---|
507 |
|
---|
508 | </body></html>
|
---|