This is a work in progress to try and capture how to be a tool friendly project

Here are the things that tend to affects tooling in a bad way if not done properly:

Change library names

Changing config semantics

Change config syntax

What to do if you did a bad thing ?

Examples of "Bad" projects

Hibernate changed the definition of the lazy property in the hbm.xml files for a specific property between micro releases. We survived because the semantics were completely broken in the first version so those who actually dependent on the feature had to move up to the latest release.

Seam changed library names a couple of times in the early days, biggest issue though were the *additions* of new dependencies which couldn't just be handled with a regular expression (if we had proper maven repositories this issue would be much smaller)

Seam changed from embedded jboss to jboss standalone or whatnot Causing difference in deployment semantics during testing. "Solved" because of fast reaction/cooperation.

ESB had new features added in the produt for the config syntax wthout a change i the verison identification. Tough since it was only discovered AFTER the runtime release.

Drools tooling depend on the runtime so much that it could not coexist.

Definition of a good tool

Support the notion of multiple runtimes and versions, the tool will outlive the projects specific version lifespan. Example of how JDT does it for java.

If your tooling is tied to a specific runtime version find the proper granularity for where to define it. Globally is very seldom the place, i.e. globally you can set a *default*, but projects, folders and in the worst case resources within the same project most likely exists and depend on different versions of your runtime.