Community Announcement - July 2020

We broke your code. We’re sorry. Here is what happened and what we’re going to do about it.

We made a big mistake with the latest release of TerminusDB, so we wanted to notify our users, explain what went wrong, how to fix it, and what we will do to prevent this from happening again.

We want to start with an apology. We value our early users, and we know you’re going out on a limb working with a very new database and a different sort of query language. We realize how frustrating it is when you work hard to make your code work with TerminusDB, only to have an update break the work you’ve spend so much effort on. We are very sorry. We also realize that mea culpa doesn’t fix your code, or recover your lost work.

What Happened

In all earlier versions of TerminusDB our error messages were often unstructured strings that were not very informative, or easy to handle. We have been planning to improve this for a while, and have replaced those strings with well formulated JSON-LD objects and much improved error messages.

What we didn’t do, however, is manage the release properly. We did not intend to make this change to our production release without first properly communicating the change to the community and helping our users to prepare. As a result this broke code which depended on existing error responses. We should not have done this, and our users have let us know that they are not happy about it.

How to Fix

The easiest way to make your code work again quickly, is to use the previous version of the server, if you are using TerminusDB Quickstart, you can just do a git pull to get the latest version, then make sure you have the master branch checked out with git checkout master
If you haven’t previously created an ENV file to set server settings, copy ENV.example to ENV

git pull
git checkout master
cp ENV.example ENV

Now, edit ENV and find the line with #TERMINUSDB_TAG=dev, uncomment the line and set the value to v2.0.4, so it looks like this:

TERMINUSDB_TAG=v2.0.4

If you have a server running stop it with ./terminusdb-container stop and then run it again with ./terminusdb-container run

You should now have the 2.0.4 version of the server running, and your old code should work. If you have any problems, please join us in one of our community channels linked below.

How we will ensure this doesn’t happen again

We will ensure to provide specifications for all API endpoints and response. We will make sure that we have full test coverage for these specifications

We will never release a minor version that breaks any of these tests

When tests need to be changed, we will make sure everybody has advanced warning and will ensure that this only happens with a major release

We are working to further integrate decision making with the community and will ensure that a discussion is started well in advance of changes that might impact users

How to reach us

If you want to participate in the decision making around future releases, get our help to fix your code or need any more information, please reach us through any of our community channels:

https://terminusdb.com/community/

1 Like