Wednesday, February 05, 2014

Killing the ATF deprecated tools code

The time to kill the deprecated tools —atf-report and atf-run principally— from the upstream ATF distribution file has come. Unfortunately, this is not the trivial task that it may seem.

But wait, "Why?" and "Why now?"

Because NetBSD still relies on the deprecated tools to run its test suite, they cannot just be killed. Removing them from the upstream distribution, however, is actually a good change for both ATF and NetBSD.

The main reason for removing the tools from the upstream ATF package is simplicity: with this change, ATF becomes a pure distribution of libraries to implement ATF-compliant test programs. At the moment, building upon ATF is difficult because the code of the libraries is overly complicated: the libraries include a lot of internal modules only used by the tools and this code cannot be lightened unless the tools are gone. Not putting this tools-only utility code outside of the base libraries was a bad design decision when the package was first created in 2007 and is a huge mess to untangle.

However, even if the tools are removed from the upstream ATF package, we still need to accommodate for the fact that NetBSD still requires the tools. The easiest way to do this is to just "hand the keys over" to NetBSD and transfer ownership of the tools code to them (which is a weird way to put it given that "them" includes me as well!). The actual effect of this "removal" is that the master copy of the tools code will live in the NetBSD source tree.

So, how is this going to happen?

A naive course of action would be to just remove the old code from the upstream distribution file in the next release. With this done, NetBSD would import the new release and, at the same time, keep the files for the old code without deleting them.

Unfortunately, this approach wouldn't work very well. The problem is, as mentioned above, that the tools have deep tentacles into the atf-c++ code and atf-c++, in turn, is mostly a wrapper over atf-c. If we did as mentioned above, changing the upstream code for atf-c++ and/or atf-c at a future date would be incredibly difficult: any minor change to their internals would result in the NetBSD copy of the tools not building any more on the next import, and that would be a huge maintenance nightmare (for me actually, because I'll continue to be the owner of the code regardless of where it lives).

Therefore, the process to perform the removal needs to account for this original deficiency and has to mitigate its effects. The plan is as follows:

  1. Detach the ATF tools from the libraries, which is tricky but necessary. Future changes to the internal structure of atf-c++ must not affect the code of the tools as should have been the case from day one. The way this is going to happen is by duplicating all code in atf-c++ that is required by the tools into the tools themselves and then killing the dependency of the tools on the libraries.
  2. Publish 0.19 as the final release with the deprecated tools: this is the release that will contain the standalone version of the code for use by anyone that may need it.
  3. Remove all ATF tools related code from the upstream tree.
  4. Publish 0.20 immediately after 0.19 as the first release without the deprecated tools. 0.19 should never hit any packaging system and will exist solely as a transition point for NetBSD (or others that may need it).
  5. Import 0.19 into the NetBSD source tree. This will rearrange the code currently existing in src/external/bsd/atf/ to isolate the old tools (with all of their supporting code) in a single and standalone subdirectory.
  6. Import 0.20 into the NetBSD source tree as well, right after 0.19. Because NetBSD does not import any of the autotools generated code, this double-import will result in minimal changes to the tree... yet it will be declaring the tools as owned by NetBSD.
  7. Upgrade existing ATF packages to 0.20, including those in pkgsrc, FreeBSD ports and Fedora, and simplify them significantly to remove any tools code. This may actually involve killing atf-libs and similar packages that were added in the past to cope with the duality of the contents of the atf package.
  8. Simplify the tools code imported into NetBSD to drop most of, if not all, the portability-related code. This implies removing anything that depends on the results of configure, for example, given that the indirection won't be needed any more.

OK, when?

Really soon. I have all the changes ready for 0.19 and 0.20 in my local git tree (which took two long-haul flights within the U.S. last week to finish!) and I'm now working on the integration into NetBSD to ensure all works. When this is ready, expect the new releases out and updated in your favorite packaging systems!

Anything else?

Doing this cleanup will free ATF to evolve more easily regrading new features and much needed interface cleanups. Of course, updating the deprecated tools in NetBSD will still have to happen whenever/if there are any incompatible changes, but doing so in a self-contained, OS-specific tree will be much simpler and palatable.

The ultimate goal, really, is to make the upstream atf package as lightweight and simple as possible.

What are your thoughts on this?