In the ArgoUML project we use several subproducts to solve parts of the problem for us. These subproducts are an important part of the ArgoUML tool and must be handled in a good way if ArgoUML is going to be successful.
When this is written (March 2004) we have had problems with the discontinuance of one of the subproducts (NSUML) and will continue to have it for well some time in the future, until we have managed to replace it. The problem with NSUML could probably not have been foreseen or avoided if this checklist would have been in place when NSUML was taken into the project but some more appearant risks with subproduct candidates might be.
Here is the list of things to check in the subproduct and to discuss with yourself and maybe with the ArgoUML development team before considering to use it in the ArgoUML project.
License
We must be allowed to develop against, release with, distribute, and use the subproduct indefinately without monetary or other compensation.
Rationale: We have no money in the ArgoUML project, we don't want to have money in the ArgoUML project. We have no organization that can enter agreements and live up to them. We don't want to require our users to enter agreements to use ArgoUML.
Java version
The subproduct must have a policy that matches the ArgoUML project policy on java version requirements.
Rationale: The ambition for ArgoUML is to be a working tool for as many people as possible. Java is still under development and there are nice features available in future releases. In ArgoUML we have a plan for how to handle this. It is to always support two major releases of Java (currently JDK 1.3 and 1.4). We cannot have a subproduct that restricts us in this aspect.
Distribution
We require the subproducts to make it possible for us to take the distribution, enter it in our CVS repository and write rules to automate the use of the subproduct while developing, releasing and running ArgoUML. This automated use must be able to run without relying on access to some server and without user intervention.
The API documentation of the subproduct (assumed to be javadoc) we can use from some web site belonging to that subproduct.
Rationale: In the ArgoUML project we want to make it as easy as possible for our users to install ArgoUML. We also want to make it as easy as possible for our developers to get their development environment working and for the release manager to prepare the releases.
Roadmap
The project developing the subproduct must have a plan that fits the ArgoUML plan for the future.
Rationale: If a subproduct will soon go somewhere else i.e. stop doing what we require or stop supporting what we require, then we will soon have troubles with that subproduct.
Working project
The project that develops the subproduct should be a working project. Check that there is some person responsible for it, preferably with a team or organization backing him. Check that there is a plan for upcoming releases. Check that there is a way to report bugs and enhancement requests.
Rationale: We don't want to rely on a subproduct where there is no chance of ever getting a bug that we encounter fixed. We are also part of an ever-evolving world. Soon we want the tool to do more for us. We should then be able to wish that and eventually get an updated subproduct.
Notice that we should not and don't need to do this in a passive way. We should explain to the subproduct team what we want and why. Especially for subproducts that we have already in ArgoUML but also for project that we consider taking in. This is to increase the likelyhood that they will have us in mind when planning and evolving.
Here are the steps to go through and the recommended order once the decision is taken to use the subproduct in ArgoUML:
Documentation
Describe in the Cookbook in the appropriate subsystem section what part of the problem that the subproduct solves and how it is used in ArgoUML.
Javadoc
Enter the package list file in a special directory under
argouml/lib/javadocs
.
Update the list of links used when building the javadocs.
One place in default.properties
,
One or two places in build.xml
(targets javadocs and javadocs-api).
Test by referencing some class from the subproduct, building the javadoc, and check that the link is working.
Repository
Assuming that the subproduct is distributed in a set of jar files,
add the jar files to the lib
directory
in a versioned way together with the license file.
Use filenames like:
, and
subproduct
-version
.jar
.
subproduct
.LICENSE.txt
A future plan is to have each subsystem in their own directory.
If the subproduct in question belongs to a subsystem that is moved to a
separate directory you should put it in
the lib
directory for that subsystem.
For the time being, there is only one
lib
directory.
Building
Assuming that the subproduct is distributed in a set of jar files,
add the jar files to the list of files that are to be included
when building ArgoUML.
One place in default.properties
,
Four places in build.xml
(targets init (tree places),
prerequisites,
package (two places),
new target check.subproduct
), and
One possibly place in AboutBox.java
(Constructor).
Notice especially that build.xml
shall not contain
any version information.
Notice also that the text in AboutBox.java
shall not contain anything that needs to be localized but just
the subproduct name, reference and possibly version.
Check by having some class from the subproduct loaded immediatly when starting ArgoUML and start using build run.
Running from modules
With the current modules set up
(in argouml/modules
) the
idea is that we are supposed to be able to start ArgoUML from any
of the modules directory.
This means that whenever changing the list of modules you will have
to update the classpaths in all these modules.
Go through the list of files argouml/modules/*/build.xml
and update.
Check by having some class from the subproduct loaded immediatly when starting ArgoUML and start in each of these directories.
Distribution
Assuming that the subproduct is distributed in a set of jar files,
add the jar files to the list of files that are to be included
when releasing ArgoUML.
One place in build.xml
(target dist-javawebstart),
One place in manifest.template
(Class-Path),
In each of the Java Web Start files (resources),
In the Info.plist
(ClassPath).
Check by having some class from the subproduct loaded immediatly when starting ArgoUML and start with java -jar argouml.jar, using each of the Java Web Start files, and from the Appbund (on a Mac).
See Section 12.8, “How to relate issues to problems in subproducts” for a discussion on how to handle bugs found in subproducts and updates of the version of a subproduct.