Fail to install the dev version following the install instructions

[seisman]

Description of the problem

The install instructions say users can install the development version using:

pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip

However, the command doesn't work and gives me the following error:

...
    LookupError: setuptools-scm was unable to detect version for '/private/var/folders/mz/d3wtwjtx4fg8qlds5lgt1c240000gn/T/pip-req-build-85cqz2ok'.

    Make sure you're either building from a fully intact git repository or PyPI tarballs. Most other sources (such as GitHub's tarballs, a git checkout without the .git folder) don't contain the necessary metadata and will not work.

    For example, if you're using pip, instead of https://github.com/user/proj/archive/master.zip use git+https://github.com/user/proj.git#egg=proj
...

Possibly related to #695.

[weiji14]

We might need to have setuptools_scm as an install only dependency. I remember reading about it somewhere but need to check.

[seisman]

Does the error message mean that

pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip

doesn't work because it doesn't contain git information, thus setuptools_scm can't determine the version?

[willschlitzer]

I'm not sure how to go about fixing this, but I assume we want this fixed before v0.3 release. Should we consider this a big enough issue to delay the release if it's not fixed in time? I'm not sure how much of an impact this will cause if it is not corrected.

[seisman]

we want this fixed before v0.3 release

Yes to me.

As I understand it, the easiest fix is changing it to

pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt

or we can encourage users to clone the repository:

git clone https://github.com/GenericMappingTools/pygmt.git
cd pygmt
make install

[weiji14]

As I understand it, the easiest fix is changing it to

pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt

Yeah, this one-liner seems to be the easiest, though it does require git to be installed I think?

[seisman]

though it does require git to be installed I think?

Yes, it clones the whole git repository, so much slower.

Another workaround is setting the parameter fallback_version to something like 0.0.0+untagged (https://github.com/pypa/setuptools_scm/#configuration-parameters).

[weiji14]

though it does require git to be installed I think?

Yes, it clones the whole git repository, so much slower.

Right. I just read the thread at pypa/pip#2432 (don't), and it seems that pip doesn't support shallow clones for philosophical reasons.

Another workaround is setting the parameter fallback_version to something like 0.0.0+untagged (https://github.com/pypa/setuptools_scm/#configuration-parameters).

This looks good. I suppose we could reset the fallback version every release (e.g. users will get 0.3.0+untagged, 0.4.0+untagged)?

Alternatively (or in addition), we could just make use of the TestPyPI uploads and let people do pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt. Based on https://stackoverflow.com/questions/34514703/pip-install-from-pypi-works-but-from-testpypi-fails-cannot-find-requirements.

[seisman]

Another workaround is setting the parameter fallback_version to something like 0.0.0+untagged (https://github.com/pypa/setuptools_scm/#configuration-parameters).

This looks good. I suppose we could reset the fallback version every release (e.g. users will get 0.3.0+untagged, 0.4.0+untagged)?

Sounds good to me.

Alternatively (or in addition), we could just make use of the TestPyPI uploads and let people do pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt. Based on https://stackoverflow.com/questions/34514703/pip-install-from-pypi-works-but-from-testpypi-fails-cannot-find-requirements.

It sounds a good addition to me.

I'm wondering if we want to use the tabbed directive in the sphinx-panels extension, to show different ways to install pygmt.

[weiji14]

This looks good. I suppose we could reset the fallback version every release (e.g. users will get 0.3.0+untagged, 0.4.0+untagged)?

Sounds good to me.

Ok, I'll start a PR for this.

Alternatively (or in addition), we could just make use of the TestPyPI uploads and let people do pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt. Based on https://stackoverflow.com/questions/34514703/pip-install-from-pypi-works-but-from-testpypi-fails-cannot-find-requirements.

It sounds a good addition to me.

I'm wondering if we want to use the tabbed directive in the sphinx-panels extension, to show different ways to install pygmt.

A bit hesitant with adding another extension. Maybe if it's used in more than one or two places, then we can start thinking about using sphinx-panels.

[seisman]

A bit hesitant with adding another extension. Maybe if it's used in more than one or two places, then we can start thinking about using sphinx-panels.

I agree.

[seisman]

Although #865 can fix the issue, I'm afraid users may still use

pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip

to install PyGMT, because it was a common way to install dev codes.

Perhaps we should still set the parameter fallback_version? To avoid updating the parameter in each release, maybe setting fallback_version to unknown, 0+unknown (default version returned by versioneer: https://github.com/python-versioneer/python-versioneer#debugging) , or 0+untagged?

[weiji14]

I can add the fallback version to PR #685 if that helps.

[seisman]

Good. I prefer 0+unknown, although it makes little difference for most users.