How do you handle versioning in a multi-sided project?

Question

I know it's a broad question so I'll try to be as specific as possible. This question is more an "organisational" question than a technical one.

We have a multi-sided project with these main components:

• A server, hosting the core business logic (data models)
• A backoffice for clients which uses the core business logic
• An application API (REST) which uses the core business logic too
• There are smartphone apps (iOS and android) using the application API
• There are another tablet app (android) different from the smartphone one using the same application API.

Soon, I'll be in production with active clients. And as any project, I'll need to maintain all different components over time. That means all of the following can be upgraded:

• the code of core business logic in the server (used by the back-office, the API, and as a side effect, by mobile apps)
• the API itself (used by both smartphone and tablet apps)
• all the mobile apps (via appstore/googleplay)

Of course, server-side parts (core business logic code and API code) can be changed immediately by myself. However, new mobile apps must be downloaded by the clients on the appstore/googleplay, and I can't be sure they're up to date.

Could you provide any guidance, good practices tips, to make theses upgrades smooth and, unrisked for the client?

Which component do I need to "version"? How to ensure everything works even if the client does not upgrade its mobile app? Should I force him to upgrade to make my work easier?

In a word, how should I organize to make my multi-sided-project live over time?

Answer 1

As you can't control when the mobile apps will be updated to a new release, you need to version at least your REST API. If you don't it will be impossible to make backwards-incompatible changes to that interface.

Besides the REST API, it is a good idea to version also the other communication interfaces that go over a network interface. That way, you are also not forced to upgrade all backoffice clients at the same time as the servers and you can implement a gradual migration to a new version with a "beta test" period.

Besides versioning the communication interfaces, you should also try to make the changes backwards compatible as much as possible. Ideally you might roll out a new interface version that still fully supports the old clients so that they don't notice anything has changed.

Answer 2

This post makes an interesting point about your question.

In a more practical way, if you have 3 components:

• 2 Consumers: a Front-End and a Mobile App
• 1 API provider: a Back-End

You could use the typical M.m.p (Major.minor.patch) versioning scheme for each but, on your Back-End url you could put something as http://youhost/M.m/resourceURI.

As you evolve and the changes in the API do not affect your contract with the consumers you keep the M.m as is in the URL. From the moment you make a change in the BackEnd that affects your consumers (be it change in behavior or an object that is different) you use a M.m+1, M+1.m+1 or M+1.m.

The way to keep things running is to deploy the new Back-End concurrently with the old, while your users install the new consumers, and slowly discontinue the older API.

You can see a way better answer than mine, here: Versioning REST API on Stackoverflow

Answer 3

For a relatively small team for development and deployment, Client N-1 compatibility model as employed by IBM Jazz may work pretty well

Try to keep clients and servers at the same version number. [Instead of managing a matrix of independent versions and their compatibilities]

Make a policy that the client version X.y.y should work with all servers versions above X.y.y but lower than X+2.0.0

For a server version 4.0, ideally there should be a client version 4.0 for every client type. However, the compatibility should be maintained so as to allow slightly different versions of clients and servers.

A client version 4.x should be compatible with servers version 4.x and above but below 6.0; A server 4.x should be compatible with all clients version 3.0 and above but less than or equal to 4.x

This way you can update a version on the server without worrying about immediate release of new versions of the clients, but will have only a well defined window of compatibility to maintain.

Ref: IBM Jazz Model [https://www.ibm.com/support/knowledgecenter/en/SSYMRC_6.0.0/com.ibm.jazz.install.doc/topics/c_n-1.html]

Answer 4

I recommend you install a continuous integration server, hook it up to your code repository and a snapshot/release repository and automate your builds. This will have a number of advantages:

1. Every component will be versioned when it is released. This includes low-level libraries as well as your final products.
2. Every code commit will trigger a snapshot build. This helps keep your developers honest, especially if you use the facility to email the culprit who broke the build.
3. Every build can run unit tests. This markedly improves code quality.
4. Every release will be tagged, so if a production fix is required, it is easy to branch from the tag and do the fix.
5. You will need to maintain a compatibility register of some sort. (e.g. BackOffice 1.0.23 is compatible with REST API 2.0.267 etc). I don't know of a tool that will help in this area.

My experience has been with open source tools: SVN, Maven 2, Jenkins and Nexus, but there are alternatives to all of these.

Don't underestimate the learning time to get your team up to speed. But once they are up to speed, they will never go back.

Answer 5

First, I'm lets start off by framing the problem a little differently. You've asked which pieces of software you need to "version". Version is an overloaded term in CS, and could mean about 100 different things. The primary things I would look at is:

1. Version Control - Version control is a configuration management tool that helps you keep track of snapshots and history of your development. ALL CODE SHOULD BE UNDER VERSION CONTROL. I don't care if it just the convenience scripts you add to your bin folder, anything that was worth spending time writing is worth the two seconds to add to a revision control software.
2. Configuration Management - How do I control what is in the build. All software should have some degree of configuration management. I like to describe to managers the difference between version control and configuration management as version control is just a tool for tracking the history of development, while configuration management is the guidelines for how we create the history, and how we do things like decide the code is good.
3. Software versioning - assigning names to releases of code. This is the thing that many people latch onto when they first see the problem because they are use to seeing "MineSweeper 7.1.29290149210" or whatever on the stuff they buy, but honestly I find this the most minor part of a much bigger problem. To be honest, just useing the hash generated by 1 and not care all that much that its not human readable is perfectly fine to do.

So since it is the most nebulous and most interesting to me, I'm just going to focus on #2. There is no one-size-fits-all, cookie-cutter solution to configuration management. Rules that work well for a team of 2 or 3 can be too loose to keep sanity in a project that takes hundreds of workers. Rules that work the big team may require way too much overhead for the small team. You'll most likely have to cobble something of your own to get something together, but I'd use the following list as a way to develop the specs for your configuration management system:

1. How can I keep track of the versions (and associated problems with them) that I am supporting in the market place?
2. How will I decide which development paths are ready for release to production systems? (It could also be ready for any other step in a process)
3. Who should have control/manage the configuration of the system? What is the workflow for adding code to be distributed to other developers?
4. How am I going to control the interaction between interacting parts? How will I know if changing a part will break the rest of the system?
5. How will we improve our configuration management system over time.

Need help answering the questions above? You should probably hire a consultant or software engineering manager...answering that can fill textbooks and is way out of scope for this type of forum.