add make version to readme for pip install

[drevicko]

pip install needs the VERSION file - make version will create that file

I also added the -U flag to pip install to force install (this is important if the user is playing with the code or trying out different older versions, as pip will not install if it thinks the git repo represents a version already installed or older than the one installed)

[balkian]

Now I think of it, this isn't right... Pip doesn't need make version. It only needs it if you install locally:

pip install .

[drevicko]

well, yes, I just tried from a freshly cloned senpy. I had trouble pip installing (or docker building?? i think it was pip) a few days ago, complained that the version file wasn't present, perhaps something changed in the meantime?

only problem with pip install . is that it installs as version 0.0:

Successfully installed senpy-0.0

After make version it installs the correct version number:

Successfully installed senpy-0.8.4

Not sure if that really matters, but I guess it's better to have the version right. Can pip be asked to attempt a make version?

ps: I thought you needed a --user but apparently not.

[balkian]

The difference is the audience. In this repo, make is for developers, pip for final users. I don't want to mix both. If that sounds weird, let me to elaborate a bit more.

You can pip install senpy anywhere, without checking out the source. Usually you'd do pip install senpy and use it as is.

make version is only needed for development. And there is already make build and make run, so you shouldn't have to use make version independently in most cases. If you use make, it will create a docker container for you, so it is reproducible.

We also build docker images like that, and tag them to the specific git version.

The whole point of using git versions in the first place is reproducible environments. To know exactly what version is causing trouble, so you can check it out and fix it. In a known environment. If you are running 0.0 or a version that is not in the repos (e.g. dirty, or unknown commits), then go back to a known version and see if you can reproduce the error.

Hope it makes sense.

On Mar 2, 2017 5:41 PM, "drevicko" notifications@github.com wrote:

well, yes, I just tried from a freshly cloned senpy. I had trouble pip installing (or docker building?? i think it was pip) a few days ago, complained that the version file wasn't present, perhaps something changed in the meantime?

only problem with pip install . is that it installs as version 0.0:

Successfully installed senpy-0.0

After make version it installs the correct version number:

Successfully installed senpy-0.8.4

Not sure if that really matters, but I guess it's better to have the version right. Can pip be asked to attempt a make version?

ps: I thought you needed a --user but apparently not.

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/gsi-upm/senpy/pull/17#issuecomment-283706807, or mute the thread https://github.com/notifications/unsubscribe-auth/AANAj8EH8yu9dosXkJeqpAJWWe3R0TyGks5rhvEggaJpZM4MQ2XV .

[drevicko]

If you are running 0.0 or a version that is not in the repos (e.g. dirty, or unknown commits), then go back to a known version and see if you can reproduce the error.

But that's exactly my point - if you clone the git repo, checkout a version (say the 0.8.2 tag), then use pip install ., the version pip think's you installed is 0.0. This is the same no matter what you checkout! Worse, if VERSION exists with some value in it (eg: 0.8.1 because you ran make when that tag was checked out) and you checkout something else (say 0.8.4) then pip install ., pip will think it's version 0.8.1! The same version ends up in senpy.__version__.

It seems to me you'd be better off with a git hook that sets the VERSION file in the way the Makefile does currently.

Another (perhaps good) option would be to commit the file VERSION at each tag.

[balkian]

Versioning is a packaging/release issue. That is why we add a VERSION only in packages (sdist) and docker images.

If you keep a VERSION in your repository, it may or may not match the git tag (which comes afterwards).

if you clone the git repo, checkout a version (say the 0.8.2 tag), then use pip install ., the version pip think's you installed is 0.0. Worse, if VERSION exists with some value in it (eg: 0.8.1 because you ran make when that tag was checked out) and you checkout something else (say 0.8.4) then pip install ., pip will think it's version 0.8.1! The same version ends up in senpy.version.

Why would anyone pip install .?

To me there are two use cases: 1) you are a normal user, so you just pip install senpy, There is a reason we upload (almost) every tag to pypi; 2) you are a developer, so you follow the defined workflow, or an equivalent.

It seems to me you'd be better off with a git hook that sets the VERSION file in the way the Makefile does currently. Not really, because hooks:

1) are local only. I cannot enforce anyone to use then. Especially when cloning. 2) only run on git operations. If you change a file in the repo, your VERSION file wouldn't change

Another (perhaps good) option would be to commit the file VERSION at each tag.

See point 2 above.

When you install manually with pip from a cloned repo there is no way for you or anyone to know if the files you're installing are the correct version or if you've changed them. At least with version 0.0 you know something's off. So I don't want to tell anyone to use make version separately.

As an aside, I also experimented with dynamically checking the VERSION in version.py. If you're on a git repository, use the tag as version. If you are not, use the VERSION file. The problem with that is that it delegates version checking to your module, which should be taken care of by your release/package tool. As a result, it both complicates your module and may cause inconsistencies.

To sum up, I'll modify the docs to differentiate dev and user workflows. I can keep your commit, tho, if you want :)

[drevicko]

Still not 100% convinced. I don't recall seeing this sort of version policy in other os projects I've worked in, but your argument isn't without merit (:

May as well drop the -U bit also - that only comes into play if you install from . then make changes then install from . again. I guess any dev worth their salt would soon know what's up.