12 Managing versioning and compatibility

 

This chapter covers

  • Thinking about versioning in the abstract
  • Planning versioning strategies for libraries
  • Designing APIs for evolution
  • Working effectively with storage schemas

There are a few topics that are almost guaranteed to cause groans from experienced engineers. If you bring up localization, merge conflicts, or time zones in conversation, be prepared for a frosty reception. Versioning falls into that category too. It’s a fact of life, but many of us put off working out how we’ll handle it for far too long—partly because it can feel like a waste of time. You’ll hear very few positive comments when a product, library or API gets versioning right, but it can be a major source of complaints when it’s done badly.

In this chapter we’ll offer some perspectives on versioning that can help you design an appropriate versioning strategy for the product you’re working on. We’ll provide some concrete guidance and suggestions, but ultimately, it will be up to you to balance competing concerns and technical challenges.

12.1 Versioning in the abstract

12.1.1 Properties of versions

12.1.2 Backward and forward compatibility

12.1.3 Semantic versioning

12.1.4 Marketing versions

12.2 Versioning for libraries

12.2.1 Source, binary, and semantic compatibility

12.2.2 Dependency graphs and diamond dependencies

12.2.3 Techniques for handling breaking changes

12.2.4 Managing internal-only libraries

12.3 Versioning for network APIs

12.3.1 The context of network API calls

12.3.2 Customer-friendly clarity

12.3.3 Common versioning strategies

12.3.4 Further versioning considerations