<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Wed Feb 07 21:11: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>[CDRIVER-1018] Documentation suggests using git, but building from git always results in warning not to use git</title>
                <link>https://jira.mongodb.org/browse/CDRIVER-1018</link>
                <project id="10030" key="CDRIVER">C Driver</project>
                    <description>&lt;p&gt;At &lt;a href=&quot;https://github.com/mongodb/mongo-c-driver/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;the mongo C driver git page&lt;/a&gt;, one suggestion is to download source from github and compile it.&lt;/p&gt;

&lt;p&gt;But it doesn&apos;t suggest which branch to use, and of the logical choices (master, r1.2, ubuntu), the configure script finishes with a warning not to use the code, that the API/ABI might change, that this is just for test purposes.&lt;/p&gt;

&lt;p&gt;build/autotools/PrintBuildConfiguration.m4&lt;/p&gt;

&lt;p&gt;Presumably there exists some branch or tag that signifies the latest stable release.  Perhaps the documentation might say so.&lt;/p&gt;</description>
                <environment>linux (ubuntu 15.10)</environment>
        <key id="240421">CDRIVER-1018</key>
            <summary>Documentation suggests using git, but building from git always results in warning not to use git</summary>
                <type id="1" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14703&amp;avatarType=issuetype">Bug</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="jesse@mongodb.com">A. Jesse Jiryu Davis</assignee>
                                    <reporter username="jeff_abrahamson">Jeff Abrahamson</reporter>
                        <labels>
                            <label>driver</label>
                    </labels>
                <created>Fri, 20 Nov 2015 12:47:36 +0000</created>
                <updated>Tue, 8 Dec 2015 02:32:37 +0000</updated>
                            <resolved>Fri, 20 Nov 2015 14:28:51 +0000</resolved>
                                                    <fixVersion>1.3.0-rc0</fixVersion>
                                    <component>docs</component>
                                        <votes>0</votes>
                                    <watches>2</watches>
                                                                                                                <comments>
                            <comment id="1098402" author="jeff_abrahamson" created="Wed, 25 Nov 2015 16:33:34 +0000"  >&lt;p&gt;That all sounds great.  Thanks.&lt;/p&gt;

&lt;p&gt;On 1, another way to phrase it so it&apos;s not too bad if you forget to change it some release might be to say something like&lt;/p&gt;
&lt;p/&gt;
&lt;div id=&quot;syntaxplugin&quot; class=&quot;syntaxplugin&quot; style=&quot;border: 1px dashed #bbb; border-radius: 5px !important; overflow: auto; max-height: 30em;&quot;&gt;
&lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot; style=&quot;font-size: 1em; line-height: 1.4em !important; font-weight: normal; font-style: normal; color: black;&quot;&gt;
		&lt;tbody &gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;  margin-top: 10px;   margin-bottom: 10px;  width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;$ git checkout 1.2.1   # or the greatest purely numeric tag number&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
			&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;
&lt;p/&gt;

&lt;p&gt;If you do 3, maybe mention in the README that building from git is possible for development, please click through.&lt;/p&gt;</comment>
                            <comment id="1098258" author="jesse" created="Wed, 25 Nov 2015 14:34:13 +0000"  >&lt;p&gt;OK, so I see two substantial improvements, maybe 3:&lt;/p&gt;

&lt;p&gt;1. In the git build instructions, instead of this:&lt;/p&gt;
&lt;p/&gt;
&lt;div id=&quot;syntaxplugin&quot; class=&quot;syntaxplugin&quot; style=&quot;border: 1px dashed #bbb; border-radius: 5px !important; overflow: auto; max-height: 30em;&quot;&gt;
&lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot; style=&quot;font-size: 1em; line-height: 1.4em !important; font-weight: normal; font-style: normal; color: black;&quot;&gt;
		&lt;tbody &gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;  margin-top: 10px;   margin-bottom: 10px;  width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;$ git checkout x.y.z  # To build a particular release&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
			&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;
&lt;p/&gt;
&lt;p&gt;Say this:&lt;/p&gt;
&lt;p/&gt;
&lt;div id=&quot;syntaxplugin&quot; class=&quot;syntaxplugin&quot; style=&quot;border: 1px dashed #bbb; border-radius: 5px !important; overflow: auto; max-height: 30em;&quot;&gt;
&lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot; style=&quot;font-size: 1em; line-height: 1.4em !important; font-weight: normal; font-style: normal; color: black;&quot;&gt;
		&lt;tbody &gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;  margin-top: 10px;   margin-bottom: 10px;  width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;$ git checkout 1.2.1  # To build the latest release tag&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
			&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;
&lt;p/&gt;
&lt;p&gt;I&apos;ve been avoiding that since it&apos;s another place I can forget to increment the version number, but I&apos;ll figure out a way to ensure it&apos;s correct.&lt;/p&gt;

&lt;p&gt;2. Tell users that if they don&apos;t check out a release tag they should expect the &quot;unstable&quot; warning.&lt;/p&gt;

&lt;p&gt;3. Delete build instructions from README so you &lt;b&gt;have&lt;/b&gt; to click through to the install guide where the details are.&lt;/p&gt;</comment>
                            <comment id="1098243" author="jeff_abrahamson" created="Wed, 25 Nov 2015 14:21:05 +0000"  >&lt;p&gt;The structure of README.rst is this&lt;/p&gt;

&lt;p&gt;...&lt;/p&gt;
&lt;ol&gt;
	&lt;li&gt;Building the Driver from Source
	&lt;ol&gt;
		&lt;li&gt;From a tarball&lt;/li&gt;
	&lt;/ol&gt;
	&lt;/li&gt;
	&lt;li&gt;Building From Git&lt;/li&gt;
&lt;/ol&gt;


&lt;p&gt;It&apos;s not at all clear there (to me) that you are advising against building from git.&lt;/p&gt;

&lt;p&gt;There&apos;s a further link to &lt;a href=&quot;http://api.mongodb.org/c/current/installing.html&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;http://api.mongodb.org/c/current/installing.html&lt;/a&gt; where the preference is stated, but that assumes someone clicks through and reads in detail.  A quick skim for needed libraries doesn&apos;t necessarily uncover the point.  Certainly I missed it the first few times.&lt;/p&gt;

&lt;p&gt;Why would I think to build from git?  Because it provides me with a way to offer feedback (patches) if I find bugs or opportunities for improvement.  Because I can easily upgrade to a new version by changing branch/tag/whatever.  Because I mostly think of downloading source tarballs as something we all did pre-github when we didn&apos;t have a choice.&lt;/p&gt;

&lt;p&gt;Why might I view tarballs as beholden of such prehistoric charm?  If I download the source tarball for x.y.z, I&apos;m highly unlikely ever even to notice that a new version is available.  If I git clone it, I&apos;m highly likely to notice.&lt;/p&gt;</comment>
                            <comment id="1098234" author="jesse" created="Wed, 25 Nov 2015 14:08:46 +0000"  >&lt;p&gt;Hi Jeff. Right, if you build off any branch you&apos;ll get the &quot;unstable&quot; warning because you are not building a release. Releases are tagged; if you build a released version from a tag like &quot;1.2.1&quot;, then you won&apos;t get the &quot;unstable&quot; warning. If you build unreleased code from a branch you get the warning.&lt;/p&gt;

&lt;p&gt;The &quot;master&quot; branch will become 1.3, and the &quot;r1.2&quot; branch will become 1.2.2.&lt;/p&gt;

&lt;p&gt;So, evidently our documentation could still use some improvement. First, can you tell me what problem you are trying to solve? What leads you to build from git instead of from a release tarball, as the instructions initially guide you to do?&lt;/p&gt;</comment>
                            <comment id="1098073" author="jeff_abrahamson" created="Wed, 25 Nov 2015 08:35:21 +0000"  >&lt;p&gt;Thanks for the response and the fix.&lt;/p&gt;

&lt;p&gt;Maybe I&apos;m missing something, but README.rst currently says&lt;/p&gt;

&lt;p&gt;    git checkout x.y.z  # To build a particular release&lt;/p&gt;

&lt;p&gt;without mention of how to determine what is the proper release to choose.  Is this obvious?  The first comment in this issue suggested I checkout 1.2.1, which is a tag rather than a branch.  If I naively think I should checkout a branch, I&apos;m lead to r1.2 as a likely release branch, and that yields the dev warning.  Looking at tags, I find 1.2.1 by using the common &quot;numerical max that has no &apos;beta&apos; or &apos;dev&apos; attached&quot; algorithm.  But maybe we could better help people who are new to the project.&lt;/p&gt;

&lt;p&gt;diff --git a/README.rst b/README.rst&lt;br/&gt;
index 34072cc..329412a 100644&lt;br/&gt;
&amp;#8212; a/README.rst&lt;br/&gt;
+++ b/README.rst&lt;br/&gt;
@@ -127,3 +127,6 @@ You can use the following to checkout and build mongo-c-driver::&lt;br/&gt;
   $ ./autogen.sh --with-libbson=bundled&lt;br/&gt;
   $ make&lt;br/&gt;
   $ sudo make install&lt;br/&gt;
+&lt;br/&gt;
+The current release tag can be found by looking at git tags and&lt;br/&gt;
+selecting the maximum value that is purely numeric.&lt;/p&gt;</comment>
                            <comment id="1094217" author="xgen-internal-githook" created="Fri, 20 Nov 2015 14:27:36 +0000"  >&lt;p&gt;Author:&lt;/p&gt;
{u&apos;username&apos;: u&apos;ajdavis&apos;, u&apos;name&apos;: u&apos;A. Jesse Jiryu Davis&apos;, u&apos;email&apos;: u&apos;jesse@mongodb.com&apos;}
&lt;p&gt;Message: &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-1018&quot; title=&quot;Documentation suggests using git, but building from git always results in warning not to use git&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-1018&quot;&gt;&lt;del&gt;CDRIVER-1018&lt;/del&gt;&lt;/a&gt; update guide for building from git&lt;br/&gt;
Branch: master&lt;br/&gt;
&lt;a href=&quot;https://github.com/mongodb/libbson/commit/1f6f49db83cea7276da0278e9e7ed9300033dc32&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/libbson/commit/1f6f49db83cea7276da0278e9e7ed9300033dc32&lt;/a&gt;&lt;/p&gt;</comment>
                            <comment id="1094211" author="xgen-internal-githook" created="Fri, 20 Nov 2015 14:21:39 +0000"  >&lt;p&gt;Author:&lt;/p&gt;
{u&apos;username&apos;: u&apos;ajdavis&apos;, u&apos;name&apos;: u&apos;A. Jesse Jiryu Davis&apos;, u&apos;email&apos;: u&apos;jesse@mongodb.com&apos;}
&lt;p&gt;Message: &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-1018&quot; title=&quot;Documentation suggests using git, but building from git always results in warning not to use git&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-1018&quot;&gt;&lt;del&gt;CDRIVER-1018&lt;/del&gt;&lt;/a&gt; update guide for building from git&lt;br/&gt;
Branch: master&lt;br/&gt;
&lt;a href=&quot;https://github.com/mongodb/mongo-c-driver/commit/4fbd8408002237a7bffb4120b48f1ca4191954d4&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/mongo-c-driver/commit/4fbd8408002237a7bffb4120b48f1ca4191954d4&lt;/a&gt;&lt;/p&gt;</comment>
                            <comment id="1094177" author="jesse" created="Fri, 20 Nov 2015 13:51:25 +0000"  >&lt;p&gt;Thanks for the report, the latest stable release is tagged &quot;1.2.1&quot;. You can see a list of releases here, including the current beta:&lt;/p&gt;

&lt;p&gt;&lt;a href=&quot;https://github.com/mongodb/mongo-c-driver/releases&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/mongo-c-driver/releases&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;You can download release tarballs from there, or use git to check out the 1.2.1 tag:&lt;/p&gt;
&lt;p/&gt;
&lt;div id=&quot;syntaxplugin&quot; class=&quot;syntaxplugin&quot; style=&quot;border: 1px dashed #bbb; border-radius: 5px !important; overflow: auto; max-height: 30em;&quot;&gt;
&lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot; style=&quot;font-size: 1em; line-height: 1.4em !important; font-weight: normal; font-style: normal; color: black;&quot;&gt;
		&lt;tbody &gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;  margin-top: 10px;   width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;git checkout 1.2.1&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;   margin-bottom: 10px;  width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;./autogen.sh --with-libbson=bundled&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
			&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;
&lt;p/&gt;
&lt;p&gt;If you&apos;re at the 1.2.1 tag when you do ./autogen.sh, there is no warning about unstable code.&lt;/p&gt;

&lt;p&gt;I&apos;ll update the guide.&lt;/p&gt;</comment>
                    </comments>
                    <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|hsej7j:</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>
                                                                                                                                                                                                                                                                    <customfield id="customfield_10557" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="781">C Driver 2015Q2 sprint 10</customfieldvalue>

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