The Modules API includes a detailed description of how versions and dependencies work technically. This documented is intended to give a policy for how to use them on netbeans.org.

The simplest case of an API change is anything that changes the public or protected signature of a public or protected class, that is a signature change which would appear in Javadoc and possibly affect clients of the API. These may be compatible or not, depending on whether any client code would be required to change in order to continue to run in binary form; and in order to compile in source form. Note that changing the set of unchecked exceptions documented to be thrown by a method, or changing whether a method is permitted to accept or return null, counts as an API change and may be compatible or not.

More subtle changes include behavioral changes where the behavior is specified in API documentation. For example, if a method is documented to call some other protected method inside its dynamic scope while holding a particular lock, ceasing to hold that lock or ceasing to call that other method would be an API change, potentially incompatible. These kinds of changes are harder to evaluate, so be careful to read the existing documentation; and when adding new documentation be careful to say exactly what you intend the behavior to be, and if the documentation includes anything that you expect could change and should not be relied on, say so. For example:

API changes must not only be documented, they must also be matched to API versioning, so module authors can programmatically depend on them.

A module should in general explicitly declare the version of every API-providing module it requires in its manifest. It is a developer’s responsibility to maintain the accuracy of this dependency at all times. For example, your project.xml might list:

to request version 3.12 or higher of the Ant module API. The IDE will forbid a user to install it if an older version of the Ant module is present (or if the module is missing altogether).

If you have made a compatible API change according to the steps above, you may now use it in your module. Make any code changes to use the new API. Also change your project.xml to require the new version. Build and test the IDE including your module with its new changes, run cvs diff, and commit the code changes and project.xml in one CVS commit.

Avoid increasing your dependency on the API version arbitrarily, as it would prevent a user interested in trying out a new version of your module from running it in an older build (such as the last release version). Of course, if you are not sure which new APIs you might be using, to be safe request the newest API version.

In order to provide an API from your module for the use of other modules, please follow these steps:

Each module should have an apichanges.xml and list of generated changes in order to track the progress of development of its APIs. Here are the steps you should take to get such list:

To use another module’s API in your module, you must declare a dependency on that module in your project.xml. Now you may import and use API classes from the "foo" module in your module’s code, e.g. org.netbeans.api.foo.FooCookie. Use of non-API classes is not permitted as your module might break unexpectedly.

If the "foo" module adds new APIs in version 1.8 which you wish to use, you must increase your dependency in the manifest to 1.8 at the same time as you make code changes to use the new APIs, and commit these together in one CVS commit. If the "foo" module changes incompatibly to e.g. org.netbeans.modules.foo/2 1.0, it will be necessary to make any needed code changes in your module, as well as to change project.xml.

Calling ClassLoader)Lookup.getDefault().lookup(ClassLoader.class.loadClass("some.other.modules.Class") to use classes from a module you do not declare a dependency on is strongly discouraged - in some cases it will work, in others it will not. In general use of reflection between modules is a poor idea, and there is generally a cleaner (and simpler) solution. Do not be afraid to split your module into a general half, and a half which additionally depends on some other module and uses its API. If you need to communicate between the two halves, do not use reflection from the general half to call into the optional half - provide a registration interface in the generic half that the optional half can use to add its functionality. This could be a simple interface and a static registration method, or it could mean using lookup APIs for a more powerful solution.

As a rule, modules should be very careful to ensure that data stored by a user is not corrupted by newer versions of a module. Settings, as opposed to development data, are generally not expected to be preserved without errors when downgrading to older versions of a module.

While developers have the responsibility to manage dependencies from their modules to both the Open APIs and other modules, and mark API changes of all sorts with changes in the module or API specification version, release engineers who publish modules also need to make version-number changes. Remember, it is never particularly harmful to increase the specification version (for example before cutting a release of a module), and either developers or release engineers may do so - such changes of course do not need any matching documentation as described above for API changes.

It is recommended that API and module specification versions in the trunk follow a two-digit scheme such as 1.5, where the next in sequence would be 1.6. On a release branch, three-digit schemes should be used, such as 1.5.1, 1.5.2, and so on. Post-release patches could have four digits, and so on.

If a number of API changes are made between releases, it may be annoying for the API specification version to be e.g. 1.133. Additionally, if specification versions of the APIs are to be used to distinguish the APIs available in each IDE release, they should be more mnemonic. So it may be useful to choose a new first digit after a release. For example, 1.20 may be branched for a release, forming 1.20.1 and so on, released as 1.20.4; meanwhile, the development builds become 2.1 rather than 1.21, so that everyone can remember that 1.x numbers mean one release, and 2.x numbers the next release.

It is important that every published release of a module have a different specification version. Otherwise automated updates cannot work correctly. Of course, if a "new version" of a module is being published solely because it was included in some bugfix build, and in fact did not contain any user-noticeable changes from the last released version, release engineers may prefer to either avoid increasing its specification version, or withhold it from the update center altogether, so as to prevent users of the previous similar version from unwittingly wasting time downloading it; but this is difficult to manage and no one currently does so.

Please remember that implementation versions of modules are not intended to be ordered. Implementation versions need not actually be numeric at all, and the IDE’s Modules API intentionally prevents inter-module dependencies from using them except as exact string comparisons. Specification versions, by contrast, must be numeric, and the only permitted comparisons in dependencies are of the form "version x.y.z or anything greater".

As a practical policy for using implementation versions, it is helpful to make them integers if they are being used in implementation dependencies from other modules, and use the build property spec.version.base in both producers and consumers of implementation dependencies in place of a fixed specification version. This trick makes management of complex sets of modules with implementation dependencies much easier. From the NBM project GUI, just check the checkbox Append Implementation Versions Automatically in the Versioning panel.

Release engineers should assume that module manifests provide complete information about which versions of what module may be run on which version of the IDE, via their major release versions, specification versions, and dependencies. Of course these assumptions should also be tested before actually publishing something on a public update server; but if any inconsistencies are found, these are P1/P2 bugs for the developer and it is better to resolve them properly in the code, than to use tricks in the update server to force certain configurations of modules to be loaded.