Update documentation on migrating and using different python versions (#305)

[festinuz]

This pull request addresses #305.

Note that its something of a draft and could use some polishing. Still, it feels like its better than nothing :)

[SethMMorton]

I think that a short blurb on what pyenv is and why it is recommended might be useful. I also think it would be very useful to demonstrate using poetry and pyenv to develop against multiple python versions, and switch between the two. I have seen it mentioned in multiple issues that one can do this, but I have not yet seen any steps on how to do this.

[jgirardet]

to give an idea:
I create a virtualenv "myvenv" my pyenv to let me choose the python version.
For example pyenv virtualenv 3.7.0 myenv.
I put in .python-version : myvenv 3.5.5 3.6.5 3.7.0.

tox is configured like for poetry's repo with envlist py35, py36,py37

So when I come inside the directory, 'myvenv" is auto activated which is cool to launch some commands easily.
I run tox to test under 3.5 3.6 and 3.7

If you do not want to use tox, you can create custom venv with pyenv with preferred python version and switch between them with pyenv local myvenv

[festinuz]

Thanks for suggestions, i'll try to come up with an update tomorrow.

By the way if any of you feel like it, i would really love some contributions, as writing an easy-to-read documentation is not my strong suit.

[jgirardet]

I formalized it : https://github.com/jgirardet/poetry/blob/master/docs/docs/basic-usage.md
But with 'my way' you do not need to install poetry for each python version. It's confusing for people if it's not the same I think (I personnaly only use the pipsi method)

[festinuz]

Oh well, it seems like we have different approaches in mind.

I myself just put the version @sdispater showed in #305. In his version you leave management of virtualenv to poetry, while in your you create virtualenvs manually.

Both approaches are valid, but i think that only one should be in the docs to avoid confusion.

.	sdispater	jgirardet
requires pyenv	yes	yes
requires pyenv-virtualenv	no	yes(?)
requires multiple poetry installs	yes	no
create virtualenv manually	no	yes
needs .python-version file	yes*	yes
is consistent	yes	no**

* WIth sdispater approach, what happens if you come from project A (python 2.7) to project B folder (python 3.6) and start to use poetry when:
A) Virtualenv is already created by poetry for this project (python 3.6)
B) Virtualenv is not created for this project
Will it use python 2.7 in both? Will it use 3.6 in one, and 2.7 in other? To be consistent it needs this file.

** Since you create your virtualenvs manually, if you share your project across multiple PCs you will run into a following problem: there will be no match for your python version set in .python-version file on any other system - That virtualenv you originally created could have any python version.

Thoughts?

[jgirardet]

Since you create your virtualenvs manually, if you share your project across multiple PCs you will run into a following problem: there will be no match for your python version set in .python-version file on any other system - That virtualenv you originally created could have any python versio

about creating virtuelenv

In every project you fork on github, the python version used by maintainer is never "included" with. You usually use your system python or what you (installed via deb or tgz file...). The maintainer only say to you : "my package works with python 3.5 and3.6 only". It's up to you to have it on your system.
So when someone clone/fork your repo he will use poetry with poetry's python version or a custom venv he created by anyway he wants : virtualenv, python -m venv, pyenv...

about testing

Where I agree with you is concerning the testing part. since the user wants to run tests with tox but can't have every supported python version, tox.ini should have the skip_missing_interpreters=True so only available interpreters will be used.

about .python-version:

I think this should not be put in vcs. It's up to the user to choose how he deals with the different python version. As an example : If use use pyenv, i'll create locally a .python-version my my desired pyenv version and use tox. but If I already have many python-version on my system not installed via pyenv, I do not need to add a .python-version

If you want to use pyenv without virtualenv with multiple poetry install you still have to use a the command pyenv local 3.7.0 and it will create a .python-version with version in it and then you'll be able to use to use poetry's specific python version.

about multiple poetry install

Since you have to update each python version, for each new poetry update, I think i'ts really cumbersome.

about choosing a default way to install or to do things

After reflexion, if documentation is clear : "you have this way with those benefits or counterpart and this way with this benefits an counter parts" I think both could live together.

end of the flood 😉

[festinuz]

Good point on upgrading poetry, that really is a "killer" in my eyes. That leaves me wondering if there is another way to manage it, as both suggested ways look sub-optimal.

[SethMMorton]

I like pyenv (I use it at home), but there may be an issue with recommending it as the only way to manage multiple python versions because it does not support windows (pyenv/pyenv#62) and it does not look like that will happen in the future either. Is there a cross-platform or windows-specific alternative that can be demonstrated/recommended as well?

[sdispater]

I am closing this PR as a lot has happened since then. The installer no longer requires to be installed for each python version and we will have #731 when version 1.0.0 lands.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.