<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Thu Feb 08 02:57:25 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary append 'field=key&field=summary' to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>MongoDB Jira</title>
    <link>https://jira.mongodb.org</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>9.7.1</version>
        <build-number>970001</build-number>
        <build-date>13-04-2023</build-date>
    </build-info>


<item>
            <title>[SERVER-1575] mechanism to change/deprecate API behaviors moving forwards</title>
                <link>https://jira.mongodb.org/browse/SERVER-1575</link>
                <project id="10000" key="SERVER">Core Server</project>
                    <description>&lt;p&gt;As progress is made maintaining backwards compatibility makes APIs grow more complicated and some default behaviors become non-intuitive.&lt;/p&gt;

&lt;p&gt;One example is that update() by default only operates on a single document without the optional &quot;multi&quot; argument telling it to do otherwise.&lt;br/&gt;
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.&lt;/p&gt;

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

&lt;p&gt;I propose a mechanism that allows both to be achieved:&lt;/p&gt;

&lt;p&gt;1) add server flags that allow specific API behavior selection&lt;br/&gt;
2) introduce a deprecation period, during which the default  API behavior is the original (or most recent) behavior&lt;br/&gt;
3) after the deprecation period, change the default to the new behavior/API spec&lt;br/&gt;
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 &quot;API-version-X&quot;, &quot;latest-API&quot; or &quot;new-features&quot; such as MYSQL does to let people develop their code with a forward-looking mentality.)&lt;/p&gt;

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

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

&lt;p&gt;With 1.6.0 just out and 1.7 starting, now might be a really good time to begin this.&lt;/p&gt;
</description>
                <environment>all</environment>
        <key id="12684">SERVER-1575</key>
            <summary>mechanism to change/deprecate API behaviors moving forwards</summary>
                <type id="4" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14710&amp;avatarType=issuetype">Improvement</type>
                                            <priority id="4" iconUrl="https://jira.mongodb.org/images/icons/priorities/minor.svg">Minor - P4</priority>
                        <status id="6" iconUrl="https://jira.mongodb.org/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="success"/>
                                    <resolution id="2">Won&apos;t Fix</resolution>
                                        <assignee username="-1">Unassigned</assignee>
                                    <reporter username="nick@leippe.com">Nick Leippe</reporter>
                        <labels>
                    </labels>
                <created>Thu, 5 Aug 2010 19:54:03 +0000</created>
                <updated>Mon, 25 Sep 2017 21:37:35 +0000</updated>
                            <resolved>Mon, 25 Sep 2017 21:37:35 +0000</resolved>
                                    <version>features we&amp;#39;re not sure of</version>
                                                    <component>Usability</component>
                                        <votes>1</votes>
                                    <watches>4</watches>
                                                                                                                <comments>
                            <comment id="1681423" author="ian@10gen.com" created="Mon, 25 Sep 2017 21:37:35 +0000"  >&lt;p&gt;I&apos;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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;</comment>
                            <comment id="1657292" author="behackett" created="Fri, 25 Aug 2017 15:53:39 +0000"  >&lt;p&gt;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:&lt;/p&gt;

&lt;ul class=&quot;alternate&quot; type=&quot;square&quot;&gt;
	&lt;li&gt;Projects should follow &lt;a href=&quot;http://semver.org/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;semver&lt;/a&gt;&lt;/li&gt;
	&lt;li&gt;Features can only be removed with a bump to the major version number&lt;/li&gt;
	&lt;li&gt;Features to be removed must be deprecated before being removed, as early as possible, with clear documentation about what to do instead (if anything).&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;Some leads believe that once you add something to your API it can never be removed, regardless of deprecation. Others believe it&apos;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.&lt;/p&gt;

&lt;p&gt;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&apos;d be happy to have the drivers team write up that policy for publication.&lt;/p&gt;</comment>
                            <comment id="1657204" author="ian@10gen.com" created="Fri, 25 Aug 2017 14:25:44 +0000"  >&lt;p&gt;&lt;a href=&quot;https://jira.mongodb.org/secure/ViewProfile.jspa?name=behackett&quot; class=&quot;user-hover&quot; rel=&quot;behackett&quot;&gt;behackett&lt;/a&gt; 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&apos; 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?&lt;/p&gt;</comment>
                            <comment id="16521" author="eliot" created="Thu, 5 Aug 2010 21:25:40 +0000"  >&lt;p&gt;Can look at this again when there is a backwards breaking change we&apos;re thinking of making.&lt;/p&gt;</comment>
                            <comment id="16520" author="nick@leippe.com" created="Thu, 5 Aug 2010 20:01:50 +0000"  >&lt;p&gt;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.&lt;/p&gt;
</comment>
                    </comments>
                    <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                <customfield id="customfield_10050" key="com.atlassian.jira.toolkit:comments">
                        <customfieldname># Replies</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>5.0</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10055" key="com.atlassian.jira.ext.charting:firstresponsedate">
                        <customfieldname>Date of 1st Reply</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>Thu, 5 Aug 2010 21:25:40 +0000</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10052" key="com.atlassian.jira.toolkit:dayslastcommented">
                        <customfieldname>Days since reply</customfieldname>
                        <customfieldvalues>
                                        6 years, 20 weeks, 2 days ago
    
                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_18254" key="com.onresolve.jira.groovy.groovyrunner:scripted-field">
                        <customfieldname>Dependencies</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue><![CDATA[]]></customfieldvalue>


                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_15850" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummary">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_10057" key="com.atlassian.jira.toolkit:lastusercommented">
                        <customfieldname>Last comment by Customer</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>true</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                            <customfield id="customfield_10056" key="com.atlassian.jira.toolkit:lastupdaterorcommenter">
                        <customfieldname>Last commenter</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>ian@mongodb.com</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_11151" key="com.atlassian.jira.toolkit:LastCommentDate">
                        <customfieldname>Last public comment date</customfieldname>
                        <customfieldvalues>
                            6 years, 20 weeks, 2 days ago
                        </customfieldvalues>
                    </customfield>
                                                                                                                        <customfield id="customfield_10000" key="com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons">
                        <customfieldname>Old_Backport</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue key="10000"><![CDATA[No]]></customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                <customfield id="customfield_10051" key="com.atlassian.jira.toolkit:participants">
                        <customfieldname>Participants</customfieldname>
                        <customfieldvalues>
                                        <customfieldvalue>bernie@mongodb.com</customfieldvalue>
            <customfieldvalue>eliot</customfieldvalue>
            <customfieldvalue>ian@mongodb.com</customfieldvalue>
            <customfieldvalue>nick@leippe.com</customfieldvalue>
    
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                        <customfield id="customfield_14254" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Product Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>1|hrnylz:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|hrg0dz:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>6618</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                            <customfield id="customfield_23361" key="com.onresolve.jira.groovy.groovyrunner:scripted-field">
                        <customfieldname>Requested By</customfieldname>
                        <customfieldvalues>
                                

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10053" key="com.atlassian.jira.ext.charting:timeinstatus">
                        <customfieldname>Time In Status</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_22870" key="com.onresolve.jira.groovy.groovyrunner:scripted-field">
                        <customfieldname>Triagers</customfieldname>
                        <customfieldvalues>
                                

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_14350" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>serverRank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>1|hs2k47:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                    </customfields>
    </item>
</channel>
</rss>