Handling Versioning for Our Shopping Cart Platform (v2.0 Code Journal)

We're progressively building a full v2.0 for our frontend shopping cart. In the "v2.0 Code Journal" entries, we'll expose some of our development tools and methods for doing so. Chances are this stuff will be useful to a dev or two out there. :)

Our user base has been steadily scaling since we launched in 2013. Today, thousands of developers are using Snipcart for e-commerce projects, all over the world. I believe we have now reached a critical mass: it has become way easier to spot widely-shared pains from the feedback signals we gather. We've become better at understanding and prioritizing developer needs.

As a result, we decided to focus on facilitating the customization of our frontend shopping cart. To accomplish this, we'll soon be shipping a v2.0 of Snipcart. This first part of our development efforts for 2016 will ease many recurring pains shared by our users. Enabling an easier visual and behavioural cart customization is also in sync with our developer freedom core value.

The aim of this Code Journal is to offer more transparency regarding our development methods & philosophy. Up until now, my friend & colleague Thibaut discussed how we optimize our frontend workflow with Gulp.js, how we refined cart customization with SASS, BEM & low specificity, and how we reorganized our file architecture & SASS variables.

Today, I'm going to address one crucial issue in shipping our improved shopping cart: versioning. ​

Considerations before updating to the upcoming v2.0

​ I want to start by making one point crystal clear: we are strongly committed to maintaining a flawless, working v1.0 for our existing users. Even when our v2.0 is released, the v1.0 will keep running just fine.

If you do upgrade to the v2.0 of our snipcart.js, however, your initial Snipcart customization will not work anymore. The markup in our shopping cart and our stylesheets has been changed for the v2.0. As you'll understand by reading our previous Code Journal entries, those changes were mandatory. They allowed us to create a more easily customizable and maintainable version of our cart. ​

How we chose to handle version numbers

​ We decided to use a simpler model of Semantic versioning. For now, we'll only release major and minor updates. Patches will be added to minor versions automatically. If we introduce a change that could have a potential impact on existing Snipcart integrations, we'll update the minor version. However, I feel it's important to mention that such minor updates didn't happen since we launched. By maintaining a strong focus on backwards compatibility, we will do our very best in keeping such minor releases to a minimum.

We will most likely inform you directly via the merchant dashboard notification center to make sure you're never out of the loop. And, of course, we'll always send out important updates via our newsletter (subscribe here). We'll also be keeping an updated changelog as soon as it becomes necessary. ​ For instance, the first release of the v2.0 will be 2.0.

You may be wondering ​why we're not doing by the book Semantic versioning. The truth is we believe it's senseless to force our users to update our script every time we ship a small, non-breaking change. ​

Assets versioning

​ We serve two important, major assets with Snipcart: ​

  1. snipcart.js
  2. snipcart.css ​ The first one is Snipcart's core; our main API client. It's the file our users are adding directly on their website. ​ As of now, the file is served at https://cdn.snipcart.com/scripts/snipcart.js. ​ In order to maintain a as is version of the v1.0, this file will remain untouched. When we release the v2.0 of the cart, the new asset will be located at https://cdn.snipcart.com/scripts/2.0/snipcart.js. ​ The same thing goes for snipcart.css, which will now be served at https://cdn.snipcart.com/themes/2.0/base/snipcart.css for the v2.0. ​ We had to modify our project setup to make sure we could push updates to version 1.0 whenever we'd need. This step is now complete, and it was one of the last before releasing the v2.0. ​

API versioning

​ Each call from snipcart.js to our API will contain the header X-Snipcart-Version (the version of the cart itself). So if you have the v1.0 of snipcart.js running on your site, we'll know that the request must go through the 1.0 gate. ​ Each request received by our application will go through a set of gates. We will be able to accept a request payload from an older version and make it pass through some entry doors that will modify it to make it acceptable for our latest version. It will then pass through a set of exit doors that will make sure the response we return is compatible with the client version. ​ If you're a bit confused, don't worry: we plan on writing more extensively about this subject later on.

Ready for the v2.0?

We sure are. Our next (and last) Code Journal entry will offer an in-depth, technical look at how to handle customization of our v2.0 shopping cart. We also plan on throwing a few different GitHub templates to jump-start Snipcart customizations.

If you enjoyed this post and found it valuable, please, take a second to share it on Twitter. As always, your thoughts and questions regarding the upcoming cart v2.0 are welcome in the comments below!

Suggested posts: