Hi all, In the recent 4.0 release, we changed the htrace-core API. The API that programs use to create traces, annotations, etc. (aka the "Java client API") went through some changes. This was necessary to clean up some core architectural issues (such as the use of overly short 64 bit IDs that will collide in a real-world deployment, or the overuse of globals.)
Since we want to make it easy for projects to integrate with HTrace, I think we should have some compatibility rules for htrace-core for the future. Specifically, I think that we should include only backwards-compatible changes to the htrace-core API in HTrace 4.x So, for example, adding a new function is OK. Deleting an existing function or altering it in an incompatible way is not. It is OK to add a new function to a public abstract base class (provided you also add a default implementation in the base), but not to add a new function to a public interface, since that would break compilation. We should save incompatible changes for HTrace 5.x. In general, each "major release" such as 4.x or 5.x should contain only compatible changes to htrace-core. There should be no guarantees between 4.x and 5.x, or between any major releases-- this is the time to address architectural debt that can't be resolved any other way. Major releases should change the namespace of htrace-core classes so that both a 4.x and a 5.x jar can reside on the same CLASSPATH, similar to how we did with 3.x and 4.x. This is important because it will require some time for downstream projects to upgrade from 4.x to 5.x, and in the meantime we must avoid CLASSPATH conflict issues. There is no requirement that tracing work when the major version of the client and the span receivers are different. However, the programs themselves should function. Let's focus on just compatibility rules for htrace-core right now, since that's where our integration issues are. The other subprojects of htrace generally don't have the same integration issues. For example, it is easy for an admin to standardize on a single version of htrace-hbase or htrace-htraced across the entire cluster. They simply install the jars for the version they want. It is not easy for that same admin to standardize htrace-core, since they might have Hadoop pulling in 4.1 and HBase pulling in 4.0. The different subprojects are also at different levels of maturity. For example, htrace-flume is still very immature, whereas htrace-htraced is starting to get more mature. So I think the subprojects should come up with their own compatibility policies rather than trying to be one-size-fits-all. This policy should only apply to publicly visible symbols in htrace-core, not to private or package-private symbols. Test functions should also not be covered, since they don't appear in the final htrace-core jar. I think having a compatibility policy for htrace-core will be very nice for the users of our core APIs. Let me know what you think. best, Colin
