On Thu, Oct 19, 2017 at 12:07:58PM -0700, Christopher Collins wrote:
> On Fri, Oct 13, 2017 at 10:18:14AM -0700, Christopher Collins wrote:
> > * Because this is an API change, it would be best to introduce it
> > slowly. The `BLE_GAP_CONN_CANCEL` event would be marked deprecated in
> > the next release, and then removed entirely in the one after that.
>
> After some discussion in the pull request page
> (https://github.com/apache/mynewt-core/pull/632), I'm not sure it makes
> sense to try to slowly "phase out" this behavior. Since this change
> represents a change in behavior, rather than the removal of
> functionality, I don't think there is a good way to deprecate it. The
> two basic options are:
>
> 1. Keep deprecated symbols in the code base, but stop using them. Apps
> will continue to build without errors, but any app relying on the old
> behavior will silently break.
>
> 2. Remove unused symbols. This may introduce build errors for some
> apps, but at least there is no silent breakage.
>
> We could also try some hybrid approach, e.g., send both types of GAP
> events when a connection is cancelled. However, I think this would do
> more harm than good (and probably introduce some new bugs!).
>
> The release policy document's section on backwards compatibility
> (https://cwiki.apache.org/confluence/display/MYNEWT/Release+and+Support+Policy#ReleaseandSupportPolicy-BackwardsCompatibility)
> is pretty clear - if an API change has the potential to break builds,
> deprecate the old behavior for at least six months before removing it.
> I think this text needs some additional language for changes such as
> this one that can't be reasonably phased in.
I propose we add the following text to the release policy:
Sometimes it is impossible or impractical to retain a deprecated
version of an API alongside the new one. For example, a change to
a callback function's type, such as the addition of a new parameter,
is difficult to introduce while still maintaining the old API. For
these types of changes, the `deprecated` state can be bypassed.
Such changes must be voted on by the community before they are
implemented.
If there are no objections, I will make this addition to the wiki.
Thanks,
Chris
