Guideline for breaking changes #124
Conversation
GOVERNANCE.md
Outdated
| A pull request that contains potential breaking changes should be kept open for | ||
| seven days at least. |
There was a problem hiding this comment.
I don't object to this, but 7 days feels like a magic number. Was there some specific reason that period was chosen? If so, can we note it in this file?
There was a problem hiding this comment.
Other voting motions have seven days as well
There was a problem hiding this comment.
How do we classify a breaking change? Like if it breaks users who indirectly use containerd like k8s?
There was a problem hiding this comment.
Not specific to k8s though.
There was a problem hiding this comment.
I understand what we are trying to prevent and in support generally; in this case, if we (maintainers) are not aware of external community impacts (e.g. breaking for K8s, not for containerd directly), how will we know when to follow this? Given this is in response (I think?) to the RRO issue, were you aware of the breaking potential and could have marked the PR as such? I just want to make sure this isn't an additional policy that we aren't actually sure how to implement.
There was a problem hiding this comment.
For the RRO issue, I was aware of that it was a breaking change, but I wasn't thinking that it was breaking much
kubernetes/enhancements#3858 (comment)
Plan B is to keep the Kubernetes Core API and the CRI API completely unmodified,
and just let the CRI runtime treat "readonly" as "recursive readonly".
This would be much easier to implement and adopt, however, small portion of users may find this to be a breaking change.
There was a problem hiding this comment.
this could become a long conversation.. How about we just mention some basic good rules that we'll do our best to consider..
Breaking changes (backward/forward)
A breaking change is a modification to a supported feature of a public service or API that breaks with prior releases (backwards) and in some cases future releases (forwards.. both potential or real).
I. Backwards - If it is necessary to consider a breaking change, effort will be made to:
a. get input from impacted parties
b. provide proper notice and workarounds
c. avoid cherry picking the change to supported releases
d. restrict breaking changes to the main branch targeted for a next major release boundary
II. Forwards - When drafting a public service/api care should be taken to keep the API free from overly restrictive content checking that would easily break in the future if for example, an additional field is added, in the future, to a passed in data structure. IOW consideration should be made to be future proof as these apis may be hosted by old containerd binaries for many years, even called by newer versions of clients where a user did not move to the latest containerd but did upgrade the client.
There was a problem hiding this comment.
Updated as suggested. Sorry for the delay.
GOVERNANCE.md
Outdated
| A pull request that contains potential breaking changes should be kept open for | ||
| seven days at least. |
There was a problem hiding this comment.
this could become a long conversation.. How about we just mention some basic good rules that we'll do our best to consider..
Breaking changes (backward/forward)
A breaking change is a modification to a supported feature of a public service or API that breaks with prior releases (backwards) and in some cases future releases (forwards.. both potential or real).
I. Backwards - If it is necessary to consider a breaking change, effort will be made to:
a. get input from impacted parties
b. provide proper notice and workarounds
c. avoid cherry picking the change to supported releases
d. restrict breaking changes to the main branch targeted for a next major release boundary
II. Forwards - When drafting a public service/api care should be taken to keep the API free from overly restrictive content checking that would easily break in the future if for example, an additional field is added, in the future, to a passed in data structure. IOW consideration should be made to be future proof as these apis may be hosted by old containerd binaries for many years, even called by newer versions of clients where a user did not move to the latest containerd but did upgrade the client.
Co-authored-by: Mike Brown <[email protected] Signed-off-by: Akihiro Suda <[email protected]>
AkihiroSuda
force-pushed
the
guideline-for-breaking-changes
branch
from
34926dc
to
27d5c8d
Compare
A pull request that contains potential breaking changes should be kept open for seven days at least.