In the ArgoUML project we use several third-party libraries. These libraries (referred to as dependencies below) are an important part of ArgoUML and must be handled carefully to ensure ArgoUML's continuing success.
The following list should be checked for any proposed new library. Where necessary, these points should be discussed with the ArgoUML development team.
- License
- We must be allowed to develop against, release with, distribute, and use the dependency indefinitely 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 dependency must have a policy that is compatible with 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 Java5 and Java6). We cannot have a dependency that restricts us in this aspect.
- Distribution
- We require the dependency to make it possible for us to take the distribution, enter it in our repository and write rules to automate the use of the dependency 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 dependency (assumed to be Javadoc) we can use from some web site belonging to that dependency.
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.
- Road map
- The project developing the dependency must have a plan that fits the ArgoUML plan for the future.
Rationale: If a dependency 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 dependency.
- Working project
- The project that develops the dependency 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 dependency 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 that included.
Notice that we should not and don't need to do this in a passive way. We should explain to the dependency team what we want and why. Especially for dependency that we have already in ArgoUML but also for dependencies that we consider taking in. This is to increase the likelihood 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 dependency in ArgoUML:
- Documentation
- Describe in the wiki for the appropriate subsystem what part of the problem that the dependency 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 Javadoc. One place in default.properties, One or two places in build.xml (targets javadocs and javadocs-api).
- Test by referencing some class from the dependency, building the Javadoc, and check that the link is working.
- Repository
- Assuming that the dependency 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: dependency-version.jar, and dependency.LICENSE.txt.
- The plan is to have each subsystem in their own directory. If the dependency in question belongs to a subsystem that is moved to a separate directory you should put it in the lib directory for that subsystem. See how the model-mdr dependencies are handled.
- Building
Assuming that the dependency 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. The files are to be copied to the argouml/build directory when performing the "package"-target. One place in default.properties, Four places in build.xml (targets init (tree places), prerequisites, package (two places), new target check.dependency), and one possible 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 dependency name, reference and possibly version.
- This will take care of running tests, building releases, and building for the purpose of developing modules.
- Check by having some class from the dependency loaded immediately when starting ArgoUML and start using build run.
See Section How to relate issues to problems in dependencies for a discussion on how to handle bugs found in a dependency and updates of the version of a dependency.