Meme API

Atleast not in one go and break apart everything that was working normally for most of the people.

The migration of the API would take part in small incremental atomic steps, which could be rolled back at any steps without breaking the system or the build.

To illustrate what this means I always keep this example of a puzzle game that was given to us in school by a teacher. So it goes like this, using only one change in a letter transform the word POOR into RICH.

Here are the rules to do the transformation

  • Each transformation should have only one letter changed.

  • In addition to this each transformation should be a meaningful english word, which means it cannot be gibbrish for example you cannot have words like POOT or ROOR.

  • All transformations cannot exceed the word length.

This is how I view the uvm API changes.

POOR – old API RICH – new API

And each change would be a small incremental change going from old API to the new API.

Here is a solution of the transformation. 
P O O R –> We start here
P O O L
P O L L
P O L E
P O P E
R O P E
R I P E
R I C E
R I C H <– We complete the transformation here
** Each change is indicated in italics

How does ATF Testing come into play?

Proper ATF test cases and testing methodology can play a very important part in modifying and introducting changes to a well established and heavily used API. Here are some things that I can think of

  • First we write up tests for the expected API to have a reference to how things are expected to work once we have completed our API transformation.

  • In our case we do not have a set of base tests for the on which we can use as a starting point reference when we start our transformation, instead Cherry (cherry@) did the neat trick of segregating the necessary parts of the existing API into a separate file, which does not break the current API but allows incremental delta changes to the current one being made in sufficient isolation. This seperated file now acts as the candidate for our base set of tests, which can be considered the starting point of the transformations.

  • Once we have a set of test cases for the base line starting point and the expected ending point of the API, each transformation can be accurarely tracked via the ATF tests. Each time a transformation happens the test(s), we can expect a break in the respective sections related to the changes in code. NOTE: This also implies that when you write the tests, it should be specific enough to break upon an API change but not break upon an implementation detail change for example changing a storage mechanism for the list of pages from a static Array to a linked list need not necessarily break the test.

The granularity of how deep the testing should be done is at the discretion of the user writing up the test cases.

Hopefully this will help both of us in transforming the current API into the new one which we expect to replace.