[CDRIVER-1018] Documentation suggests using git, but building from git always results in warning not to use git Created: 20/Nov/15  Updated: 08/Dec/15  Resolved: 20/Nov/15

Status: Closed
Project: C Driver
Component/s: docs
Affects Version/s: None
Fix Version/s: 1.3.0-rc0

Type: Bug Priority: Major - P3
Reporter: Jeff Abrahamson Assignee: A. Jesse Jiryu Davis
Resolution: Done Votes: 0
Labels: driver
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

linux (ubuntu 15.10)



 Description   

At the mongo C driver git page, one suggestion is to download source from github and compile it.

But it doesn'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.

build/autotools/PrintBuildConfiguration.m4

Presumably there exists some branch or tag that signifies the latest stable release. Perhaps the documentation might say so.



 Comments   
Comment by Jeff Abrahamson [ 25/Nov/15 ]

That all sounds great. Thanks.

On 1, another way to phrase it so it's not too bad if you forget to change it some release might be to say something like

$ git checkout 1.2.1   # or the greatest purely numeric tag number

If you do 3, maybe mention in the README that building from git is possible for development, please click through.

Comment by A. Jesse Jiryu Davis [ 25/Nov/15 ]

OK, so I see two substantial improvements, maybe 3:

1. In the git build instructions, instead of this:

$ git checkout x.y.z  # To build a particular release

Say this:

$ git checkout 1.2.1  # To build the latest release tag

I've been avoiding that since it's another place I can forget to increment the version number, but I'll figure out a way to ensure it's correct.

2. Tell users that if they don't check out a release tag they should expect the "unstable" warning.

3. Delete build instructions from README so you have to click through to the install guide where the details are.

Comment by Jeff Abrahamson [ 25/Nov/15 ]

The structure of README.rst is this

...

  1. Building the Driver from Source
    1. From a tarball
  2. Building From Git

It's not at all clear there (to me) that you are advising against building from git.

There's a further link to http://api.mongodb.org/c/current/installing.html where the preference is stated, but that assumes someone clicks through and reads in detail. A quick skim for needed libraries doesn't necessarily uncover the point. Certainly I missed it the first few times.

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't have a choice.

Why might I view tarballs as beholden of such prehistoric charm? If I download the source tarball for x.y.z, I'm highly unlikely ever even to notice that a new version is available. If I git clone it, I'm highly likely to notice.

Comment by A. Jesse Jiryu Davis [ 25/Nov/15 ]

Hi Jeff. Right, if you build off any branch you'll get the "unstable" warning because you are not building a release. Releases are tagged; if you build a released version from a tag like "1.2.1", then you won't get the "unstable" warning. If you build unreleased code from a branch you get the warning.

The "master" branch will become 1.3, and the "r1.2" branch will become 1.2.2.

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?

Comment by Jeff Abrahamson [ 25/Nov/15 ]

Thanks for the response and the fix.

Maybe I'm missing something, but README.rst currently says

git checkout x.y.z # To build a particular release

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'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 "numerical max that has no 'beta' or 'dev' attached" algorithm. But maybe we could better help people who are new to the project.

diff --git a/README.rst b/README.rst
index 34072cc..329412a 100644
— a/README.rst
+++ b/README.rst
@@ -127,3 +127,6 @@ You can use the following to checkout and build mongo-c-driver::
$ ./autogen.sh --with-libbson=bundled
$ make
$ sudo make install
+
+The current release tag can be found by looking at git tags and
+selecting the maximum value that is purely numeric.

Comment by Githook User [ 20/Nov/15 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1018 update guide for building from git
Branch: master
https://github.com/mongodb/libbson/commit/1f6f49db83cea7276da0278e9e7ed9300033dc32

Comment by Githook User [ 20/Nov/15 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1018 update guide for building from git
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/4fbd8408002237a7bffb4120b48f1ca4191954d4

Comment by A. Jesse Jiryu Davis [ 20/Nov/15 ]

Thanks for the report, the latest stable release is tagged "1.2.1". You can see a list of releases here, including the current beta:

https://github.com/mongodb/mongo-c-driver/releases

You can download release tarballs from there, or use git to check out the 1.2.1 tag:

git checkout 1.2.1
./autogen.sh --with-libbson=bundled

If you're at the 1.2.1 tag when you do ./autogen.sh, there is no warning about unstable code.

I'll update the guide.

Generated at Wed Feb 07 21:11:18 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.