<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Thu Feb 08 08:21:18 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>[DRIVERS-341] Drivers should use https://docs.mongodb.com/master/ for documentation permalinks</title>
                <link>https://jira.mongodb.org/browse/DRIVERS-341</link>
                <project id="10980" key="DRIVERS">Drivers</project>
                    <description>&lt;p&gt;I&apos;ve had some discussions with &lt;a href=&quot;https://jira.mongodb.org/secure/ViewProfile.jspa?name=kay.kim&quot; class=&quot;user-hover&quot; rel=&quot;kay.kim&quot;&gt;kay.kim&lt;/a&gt; in &lt;a href=&quot;https://jira.mongodb.org/browse/DOCS-9162&quot; title=&quot;Permalinks for development release documentation topics?&quot; class=&quot;issue-link&quot; data-issue-key=&quot;DOCS-9162&quot;&gt;&lt;del&gt;DOCS-9162&lt;/del&gt;&lt;/a&gt; and more recently offline about how drivers docs should permalink to server docs.  Now that we&apos;ve just shipped, I&apos;d like to make a driver-wide proposal for how to do this consistently in the next cycle.&lt;/p&gt;

&lt;p&gt;&lt;b&gt;Our chicken-and-egg problem&lt;/b&gt;:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;Drivers documenting new or changed server features want to link to the official server manual for details.&lt;/li&gt;
	&lt;li&gt;Server documentation changes won&apos;t be published in the database manual until the server ships.&lt;/li&gt;
	&lt;li&gt;Drivers want to ship/publish documentation before the server ships to allow testing against development releases.&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;&lt;b&gt;Recommended solution&lt;/b&gt;:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;Drivers use &lt;tt&gt;&lt;a href=&quot;https://docs.mongodb.com/master/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://docs.mongodb.com/master/&lt;/a&gt;&lt;/tt&gt; as a permalink prefix&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;&lt;b&gt;How it would work&lt;/b&gt;:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;When new server docs are written, they are immediately visible in the &apos;master&apos; URL.&lt;/li&gt;
	&lt;li&gt;Drivers link to &apos;master&apos; URLs so that users can see and use docs during testing.&lt;/li&gt;
	&lt;li&gt;When the server ships, &apos;master&apos; and &apos;manual&apos; URLs have identical content.&lt;/li&gt;
	&lt;li&gt;Eventually, &apos;master&apos; diverges to add new features or changes for the next server release.&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;&lt;b&gt;Pros&lt;/b&gt;:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;Drivers only have to write documentation URLs once.&lt;/li&gt;
	&lt;li&gt;New-feature documentation readily available for RCs before server ships.&lt;/li&gt;
	&lt;li&gt;No race to update URLs from &apos;master&apos; to &apos;manual&apos; right at ship time.&lt;/li&gt;
	&lt;li&gt;No tickets to update them from &apos;master&apos; to &apos;manual&apos; later after the server team ships (i.e. no &quot;doc patch&quot; release necessary).&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;&lt;b&gt;Cons&lt;/b&gt;:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;The &apos;master&apos; will periodically diverge from &apos;manual&apos;, meaning drivers will sometimes be pointing users to an &quot;in development&quot; version of the manual.&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;Personally, I think the &quot;con&quot; is minor: the server version the manual applies to is visible on the page and many features will have no divergence from release to release anyway.&lt;/p&gt;</description>
                <environment></environment>
        <key id="334986">DRIVERS-341</key>
            <summary>Drivers should use https://docs.mongodb.com/master/ for documentation permalinks</summary>
                <type id="3" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14718&amp;avatarType=issuetype">Task</type>
                                            <priority id="3" iconUrl="https://jira.mongodb.org/images/icons/priorities/major.svg">Major - P3</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="9">Done</resolution>
                                        <assignee username="bernie@mongodb.com">Bernie Hackett</assignee>
                                    <reporter username="david.golden@mongodb.com">David Golden</reporter>
                        <labels>
                    </labels>
                <created>Tue, 29 Nov 2016 21:52:50 +0000</created>
                <updated>Fri, 2 Nov 2018 18:08:39 +0000</updated>
                            <resolved>Fri, 28 Jul 2017 19:42:48 +0000</resolved>
                                                                            <votes>0</votes>
                                    <watches>6</watches>
                                                                                                                <comments>
                            <comment id="1445287" author="behackett" created="Tue, 29 Nov 2016 22:15:02 +0000"  >&lt;p&gt;PyMongo makes heavy use of &quot;dochub&quot; links. Those redirects are supposed to work for forever. Has that fallen out of favor?&lt;/p&gt;

&lt;p&gt;&lt;a href=&quot;https://github.com/mongodb/mongo-python-driver/blob/3.4.0/bson/objectid.py#L16&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/mongo-python-driver/blob/3.4.0/bson/objectid.py#L16&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;My concern is that non-dochub links will break at some future date.&lt;/p&gt;</comment>
                    </comments>
                <issuelinks>
                            <issuelinktype id="10012">
                    <name>Related</name>
                                            <outwardlinks description="related to">
                                        <issuelink>
            <issuekey id="201364">DRIVERS-227</issuekey>
        </issuelink>
                            </outwardlinks>
                                                                <inwardlinks description="is related to">
                                                        </inwardlinks>
                                    </issuelinktype>
                    </issuelinks>
                <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                            <customfield id="customfield_15850" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummary">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|hssc8f:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>9223372036854775807</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        </customfields>
    </item>
</channel>
</rss>