We had an extended discussion around this in the last community sync.
Thanks for those who participated!
To sum up the discussion:
--> As mesos devs, we should strive to not make incompatible changes in
APIs, flags, environment variables.
--> In the rare case where an incompatible change is preferred (e.g., code
complexity), we should give a clear 6 months heads up the users that a
breaking change is going to take place.
--> Breaking changes do not necessitate a major version bump. This is
because we want to allow live upgrades between major versions (e.g., 1.10
to 2.0).
--> Compatibility guarantees do not apply to experimental features (incl.
APIs).
--> We need to have clear documentation about procedure that devs could
follow when deprecating/removing stable features and adding experimental
features.
--> We need to improve upgrades.md to make it easy for operators to know
what features are deprecated/removed between versions X and Y.
--> We should decouple internal protos used by Mesos from the unversioned
protos used by driver based frameworks.
I will spend some time in the next few weeks to create/update the
documentation reflecting these points.
Anything else I missed?
Thanks,
On Sat, Oct 15, 2016 at 11:47 AM, haosdent wrote:
> Thanks @yan's great inputs! I couldn't agree more almost of them.
>
> > Also the API is not just what the machine reads but all the documentation
> associated with it, right? It depends on what the documentation says; what
> the user _should_ expect.
>
> I think different users may have different expectations. And the guy who
> developed the APIs may have different understand from some users as well.
> Our documentations should cover most of cases.
>
> But in case that we didn't or forgot to write it explicitly in the
> document, should we give up to update the API? Just like user Alice said
> this is a BUG while user Bob said this is a feature. I think we still need
> to raise it case by case to ensure most users are not affected by the
> breaking API changes.
>
> On Sat, Oct 15, 2016 at 6:55 AM, Vinod Kone wrote:
>
> > We will chat about this in the upcoming community sync (thursday 3 PM).
> > So, please make sure to attend if you are interested.
> >
> > On Fri, Oct 14, 2016 at 3:44 PM, Yan Xu wrote:
> >
> >>
> >> On Fri, Oct 14, 2016 at 3:37 PM, Yan Xu wrote:
> >>
> >>> Thanks Alex for starting this!
> >>>
> >>> In addition to comments below, I think it'll be helpful to keep the
> >>> existing versioning doc concise and user-friendly while having a
> dedicated
> >>> doc for the "implementation details" where precise requirements and
> >>> procedures go. Maybe some duplication/cross-referencing is needed but
> Mesos
> >>> developers will find the latter much more helpful while the
> users/framework
> >>> developer will find the former easy to read.
> >>>
> >>> e.g., a similar split:
> >>> https://github.com/kubernetes/kubernetes/blob/master/docs/api.md
> >>> https://github.com/kubernetes/kubernetes/blob/master/docs/de
> >>> vel/api_changes.md (which has a lot of details on how the kubernetes
> >>> community is thinking about similar issues, which we can learn from)
> >>>
> >>> Jiang Yan Xu
> >>>
> >>> On Wed, Oct 12, 2016 at 9:34 AM, Alex Rukletsov
> >>> wrote:
> >>>
> Folks,
>
> There have been a bunch of online [1, 2] and offline discussions about
> our
> deprecation and versioning policy. I found that people—including
> myself—read the versioning doc [3] differently; moreover some aspects
> are
> not captured there. I would like to start a discussion around this
> topic by
> sharing my confusions and suggestions. This will hopefully help us
> stay
> on
> the same page and have similar expectations. The second goal is to
> eliminate ambiguities from the versioning doc (thanks Vinod for
> volunteering to update it).
>
> >>>
> >>> +1 Let me know if there are things I can help with.
> >>>
> >>>
>
> 1. API vs. semantic changes.
> Current versioning guide treat features (e.g. flags, metrics,
> endpoints)
> and API differently: incompatible changes for the former are allowed
> after
> 6 month deprecation cycle, while for the latter they require bumping a
> major version. I suggest we consolidate these policies.
>
> >>>
> >>> I feel that the distinction is not API vs. semantic changes, Backwards
> >>> compatible API guarantee should imply backwards compatible semantics
> (of
> >>> the API).
> >>> i.e., if a change in API doesn't cause the message to be dropped to the
> >>> floor but leads to behavior change that causes problems in the system,
> it
> >>> still breaks compatibility.
> >>>
> >>> IMO the distinction is more between:
> >>> - Compatibility between components that are impossible/very unpleasant
> >>> to upgrade in lockstep - high priority for compatibility guarantee.
> >>> - Compatibility between components that are generally bundled (mod