[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
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:
Say this:
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 ...
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 | ||
| 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: | ||
| 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: | ||
| 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:
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. |