Environment Independent Versions

In the recommendation for designing versionable contract names, there was no mention of the deployment environment of the service. Should this be included by, for example, having different namespaces for development and production deployments of the service?

I generally don’t recommend including the deployment environment in the contract name. Instead, base the versioning scheme on the technical compatibility of the two implementations. As a service moves between development, testing, and production deployments, keep the same name if the implementation is stable and use a different name when the implementation changes.

There are a few reasons for this:

You want to be able to test exactly what will be used in production. Even supposedly insignificant changes can introduce defects. There should be no difference between using a namespace that contains the word “test” and a namespace that contains the word “final”. However, what if some library that’s being used has a size limit for the namespace and adding one character causes it to stop working? What if someone’s written some debugging code that’s looking for the word “test” to appear?

After initial deployment of the system, the transition between environments is likely to be haphazard. If you’re working on a bug for a specific component you might have a few of the services running locally, a few deployed somewhere else, and for the components that you’re not working on, using data from the actual production services. Having a mishmash of names as you pull parts of the system from one environment to another can be error prone.

Changing names adds another task to the list of steps needed to move between environments. Many systems already have a fairly extensive task list to perform during deployment. Simplifying this process is always appreciated, particularly if the tasks are difficult to automate or require special skills. It may be easy for you to remember how to create a special build with the right options set for the staging environment, but a lab technician or new developer coming in is going to have to learn all of that too before they can be productive.