[SERVER-1575] mechanism to change/deprecate API behaviors moving forwards Created: 05/Aug/10  Updated: 25/Sep/17  Resolved: 25/Sep/17

Status: Closed
Project: Core Server
Component/s: Usability
Affects Version/s: features we're not sure of
Fix Version/s: None

Type: Improvement Priority: Minor - P4
Reporter: Nick Leippe Assignee: Unassigned
Resolution: Won't Fix Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

all


Participants:

 Description   

As progress is made maintaining backwards compatibility makes APIs grow more complicated and some default behaviors become non-intuitive.

One example is that update() by default only operates on a single document without the optional "multi" argument telling it to do otherwise.
This is counter intuitive to anyone coming from SQL as well as inconsistent with other API calls such as find() which returns all matches without an additional limit() modifier.

Breaking backwards compatibility is generally bad, but becomes necessary in order to improve the API and keep it intuitive and clean moving forward.

I propose a mechanism that allows both to be achieved:

1) add server flags that allow specific API behavior selection
2) introduce a deprecation period, during which the default API behavior is the original (or most recent) behavior
3) after the deprecation period, change the default to the new behavior/API spec
4) attempts to use old behavior can become errors that return/raise exceptions, thus finding code that uses old behavior becomes a matter of normal debugging for those wishing to update code to the current API behavior. (This can obviously be done during the deprecation period by changing the default via the server flags. A catch-all flag could be added such as "API-version-X", "latest-API" or "new-features" such as MYSQL does to let people develop their code with a forward-looking mentality.)

Anyone that needs to maintain old behavior for old code can simply add the appropriate server flag switch.
A long enough deprecation period, or simply visible-enough (documentation-wise) exposition of such changes will suffice to not leave anyone confused.

This is really nothing new--many other projects do this or something very similar. I think mongodb will benefit from doing so as well.

With 1.6.0 just out and 1.7 starting, now might be a really good time to begin this.



 Comments   
Comment by Ian Whalen (Inactive) [ 25/Sep/17 ]

I'm resolving this ticket as there are no plans for specific functionality to be added to the server that covers behavior selection/feature deprecation/etc.

However, the Server team will be working with the Drivers team (as primary consumers of the Server API) to create a clearly documented deprecation policy and process.

Comment by Bernie Hackett [ 25/Aug/17 ]

There is a lot of disagreement in the drivers org about deprecation and removal of legacy APIs and behavior. The things we all agree on are:

  • Projects should follow semver
  • Features can only be removed with a bump to the major version number
  • Features to be removed must be deprecated before being removed, as early as possible, with clear documentation about what to do instead (if anything).

Some leads believe that once you add something to your API it can never be removed, regardless of deprecation. Others believe it's always fine to remove things. Others take the middle road and decide if to remove and when on a case by case basis. The opinions are usually colored by the standards of the language community the lead works in most often.

I think we should have a discussion about this with representatives from across engineering and try to come up with a policy everyone can agree on. I'd be happy to have the drivers team write up that policy for publication.

Comment by Ian Whalen (Inactive) [ 25/Aug/17 ]

behackett The Storage team looked at this while reviewing old tickets not assigned to a team and thought this might actually be better represented as DRIVERS ticket that goes through the Drivers' public specification process? Does that make sense to you? Any other thoughts on where this work should land? Is it possible this is actually already done in most/all of the drivers?

Comment by Eliot Horowitz (Inactive) [ 05/Aug/10 ]

Can look at this again when there is a backwards breaking change we're thinking of making.

Comment by Nick Leippe [ 05/Aug/10 ]

Also, depending on how the server and some behaviors are implemented, some behaviors might even be configured/selected at runtime on a per-client/connection basis. This would be even more flexible.

Generated at Thu Feb 08 02:57:24 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.