governance/resolutions/20170620-volunteer-support.rst

2017-06-20 Definition of Upstream Support

Here we clarify what we mean by "upstream supports this feature" and "upstream does not support this feature". We do that by looking at some of the necessary conditions for "upstream support".

The upstream codebase is created and maintained by a community of volunteers. As such, neither the TC, PTL or project teams are able to assign tasks to contributors. In addition, its worth noting that many of those working on upstream only spend part of their working week focused on upstream.

The Apache 2 license used by the community is clear about the lack of Warranty and Liability. This document does not seek to contradict that.

Given all this, the term "upstream support" is more complicated than it would first appear. It could be getting a reply to a mailing list post, fixing a bug you reported, getting your code reviewed and merged, getting help in IRC to debug a production issue or something else. In this document we describe what needs to be in place to help provide some level of "upstream support".

Implemented Upstream

If something has not been implemented, it is sure not to work and clearly can't be "supported" in any way.

We can ask these questions:

• Has someone implemented support for this upstream?
• Has this been implemented in an out-of-tree driver?
• Is the publicly available code for the out-of-tree driver useful when debugging problems in that driver?

Upstream can only be expected to support something that is implemented in the upstream code base.

Continuously Tested

When something is tested on every proposed patch, we quickly know if the proposed patch will break the feature or deployment the tests are validating. In addition, there are certain tests code must pass before the code can be merged into master; we call these gating tests.

Should any patch break one of the above tests, that patch author needs to work with the community to get the tests passing before their code will merge. It seems reasonable to say deployments and features that have this level of testing are, in some sense, "supported upstream".

When something is not tested, history has proven those features quickly stop working. As such, something that is not tested, should be assumed to be broken and not supported.

Full Upstream Participation

While having something implemented and continuously tested is required to claim any level of "upstream support", there are many other aspects to having a well maintained feature or driver.

The team maintaining the code must work in the open, for both bug fixes and feature development. That allows for prompt replies about bugs you need fixing. Even if the reply says it will not be fixed, its better than being left in the dark about what is wrong. In a similar way, if you create a fix, you would like that to be reviewed and included in future release in a timely manner.

In a similar way, you want confidence that the feature/driver will continue to work across upgrade. If those maintaining that feature or driver are actively involved in upstream design discussions, it is much more likely what you rely on will continue to work as the system evolves.

Deprecation

In extreme cases, if a feature or driver can no longer be maintained, the implementation must be removed. Projects that are stable and widely deployed are expected to sign up for the tag-assert:follows-standard-deprecation. This gives us a controlled way to warn users about such features or drivers that are being replaced or at risk of being removed.

OpenStack is a volunteer community. Should some parts of the codebase no longer have anyone stepping up to maintain them, it would be unfair to not warn our users of the risk this creates. In particular, if there is no reliable testing of a particular part of the code, or a particular deployment scenario, it is hard for the community to keep that functioning as the upstream code evolves. Moreover, it is hard to review bug fixes to those parts of the code, because there is no testing to help prove the proposed fix improves the situation for all users of that part of the code base. In many cases, the best action is to remove the implementation from the codebase, subject to the above deprecation process.

If we never removed features that are proving hard to support, there would be many other problems for a much wider part of the community. People who try the feature will find it broken, and assume that's normal for all OpenStack features. In a similar ways, developers get complacent about parts of the code that are known to have issues, and the overall quality will drop.

It is healthy to remove some features and simplify things as we move forward. Over time it becomes clear that particular solutions turned out to be the wrong way to do things, so its important to transition people to the better solution. This helps existing users move to a single more stable code base, and stops confusing new users that have to spend time working out which option it the best one for them. Clearly this needs to be balanced against maintaining API compatibility.

For clarity, deprecation is not a one way process. It is a process that has many possible outcomes. Consider these points about deprecation:

• Upstream, it's often hard to know if anyone uses the feature, and if those people do exist, whether they really rely on that feature or use it because they didn't know there was a better way forward.
• We warn users there might be problems we don't know about, and we are no longer in a position to accept fixes.
• For new deployments, it signals that it is best to choose another way to solve your problem.
• Many times there is a different more preferred way to solve the problem, so users can switch to a different way of solving their problem.
• For people that really rely on the feature we are removing, this gives them a great opportunity to step up and help stop the feature from being removed by helping work out how best to maintain the feature upstream.
• Sometimes, after several attempts to get people to step up and maintain a feature, it keeps falling into disrepair. At this point, a new approach is likely needed to keep the feature working.

Downstream Support

For the avoidance of doubt, because a technology choice is not supported upstream, this does not mean it can't be supported downstream in a particular OpenStack distribution or service offering.

However if you rely on something that is not supported upstream, you need to consider the level of vendor lock-in / reliance you are willing to accept, taking into account how disruptive a migration to something more widely supported might be.

Many vendors offer an SLA and/or guarantee around addressing issues and bugs you find in your deployment. In a similar way, you can pay some vendors to get a specific feature added. Upstream does not do any of these things.