Maintenance model for external artifacts

Question

When we think about maintaining a software solution holistically, we have to think about things like non-code change control and configuration management, in addition to the actual source code. For example, for maintaining a large web application, tracing:

"Make the following (manual) configuration change to the farm, as part of deploying this specific xx.yy.zz version of the solution package."

I've implemented a fairly good model for this, but now I'm tackling the next largest problem - how do we manage changes in other systems we don't own? Let's take a simple example:

We have an ASP.NET application owned by a solution team (let's call them the PLM Team). Their next release includes a change that requires the SAP team (which is under a different maintenance umbrella) to also deploy a change to one of their BAPI endpoints.

Of course the actual coordination of the deployment at release time is simple human interaction & coordination, but in terms of the total SDLC:

• How does our example "PLM Team" package & trace this dependency as an artifact, both as an upcoming change and, post-deployment, a managed dependency with requirements they own but an implementation they do not directly control?
• What is the right information to capture about it? How should it be treated differently than non-code configuration items they do control?

Answer 1

• If two teams communicate constantly, it's rather about human interaction and coordination, not about business processes. You just agree how the interface used by both projects will change, you implement the change, and you deploy both products at the same time. By the same time, I mean you disconnect a machine from a farm, you stop both apps, then updates are applied to both apps, and then they start running again and the machine can get back to the farm.

• If two teams cannot communicate very well (either because they are located in different cities geographically or because they hate one another, or whatsoever), there is really nothing you can do from business process perspective to update both applications at the same time.

In this second case, you're in a role of a large API provider who released a new version of the API, but has lots of customers who are still using the old version. If the next version does not extend¹ the first one, but changes² it, you should keep running both versions.

This means that you will have both:

http://api.example.com/products/get/5

and:

http://api.example.com/v2/d6w9UbnZ50/products/get/5
                       ↑       ↑
                    version  token

and while the new clients will be able to benefit from the RESTfull API by using the second version, the older clients who rely on sessions will still be able to use the API.

Since your project is used by only one other project, both developing and maintaining two versions of the same project is cost-prohibitive. This means that once the second version developed and tested, you should try whatever you can to force the other team to start using the second version as soon as possible. This also means that if they open a ticket telling that there is a bug in your first version, this ticket must be immediately closed as "won't solve" with a note that the first version is not maintained any longer.

---

^{¹ Extending: adding an optional argument to en existent method or adding an overload or a new method doesn't break the current API.}

^{² Changing: renaming methods to make them more explicit or removing an argument or adding a mandatory one will break the current API.}