How to run pip from sources (fixes #5747) #5752
Conversation
|
Sphinx didn't complain about unused |
|
I don't think we need to describe how to use virtualenv in this documentation. Or how to git clone. I've only skimmed through this so I won't say more about this until I take a better look. |
| $ git clone https://github.com/pypa/pip | ||
| $ cd pip | ||
|
|
||
| Then run `python src/pip`: |
There was a problem hiding this comment.
there needs to be a big fat warning here on why this works and that this absolutely doenst work for running the testsuite that ensure pip works ^^
There was a problem hiding this comment.
The explanation why it works is below. And there is no visible way to run tests without tox, so people have to read about tox below anyway.
There was a problem hiding this comment.
Even with the requested changes I have strong concerns about the whole tone and approach of the text - we should assume that people wanting to work on pip have at least a basic understanding of development workflows and are willing to use them - so why isn't "just use virtualenv and editable installs, like you would do for any other project" enough (and given that, why does it need saying?)
| @@ -8,7 +8,55 @@ This document is meant to get you setup to work on pip and to act as a guide and | |||
| reference to the the development setup. If you face any issues during this | |||
| process, please `open an issue`_ about it on the issue tracker. | |||
|
|
|||
| Development tools | |||
| Running Developent Version | |||
| ========================== | |||
There was a problem hiding this comment.
You don't say why anyone would want to do this (apart from running the tests, which as you say this approach doesn't work for...)
There was a problem hiding this comment.
I skipped the intro, because I feel like this part should be in TL;DR section. People who don't needed it can easily skip this section. In fact, I think the auditory of development docs are only two groups of people - newcomers (setup), and occasional contributors who forget things (me).
My goal is to have a quick reference for rebasing and manual testing that my patches still work. For that I need only a single python src/pip line. But I would like to help people coming for an easy or good-first-issue from funnels (marketing) like OpenHatch and upcoming HacktoberFest to have more fun with pip than virtualenv. Just grab someone experienced from Ruby or Node.js background and ask them to run pip from sources. These are the people that I have in mind.
| from the clone directory. This way they do not need to be installed on your | ||
| system. The process of bundling dependencies with a project sources is called | ||
| `vendoring`, but because there is no PEP for that, other Python won't work | ||
| this way and still require `pip` for installation. |
There was a problem hiding this comment.
This makes no sense. Why would there be a PEP for vendoring? What do you mean by "other Python won't work this way"?
There was a problem hiding this comment.
I said that to warn people that vendoring in pip is probably a hack, and not something supported by language like vendor directories in Go or something approved by community as a general practice. I do this, because Python community is lawful good when it comes to proven things (e.g. nobody do monkey-patching, even if it is possible) and usually devise a PEP to mark something as generally worthy to let people know and allow tools to build around that.
If there is a way for other project to adopt pip-style vendoring for their own project, I would be happy to replace that paragraph with a link to the tutorial, because it is a valuable feature. For me it was a major selling point to contribute to Spyder, SCons and quite a few other projects.
| this way and still require `pip` for installation. | ||
|
|
||
| If you want to practice `virtualenv` development, then `pip` inside can be | ||
| relinked directly to development sources by installing it in |
There was a problem hiding this comment.
This is very confusingly worded. If you're just saying "this is how you use virtualenv for development" then fine, but it doesn't read like that. And anyway, using virtualenv and editable installs for development isn't a workflow that's specifically for pip, so while this section might be helpful for the odd person who doesn't know how to do it, it's not really needed in general.
Also, this is much more reliable than your proposed "just run pip" approach, so I'd rather see this as the default approach, with your suggestion only recommended for people who (for whatever reason - I can't honestly think of any reasonable ones) don't want to use a virtualenv.
There was a problem hiding this comment.
I didn't like the wording too, but I want to explain the how --editable option works. The way it is explained by pip is by vague reference to setuptools documentation:
-e, --editable <path/url> Install a project in editable mode (i.e. setuptools "develop mode") from a local
project path or a VCS url.
Which look like undocumented - you won't find find this mode in setuptools docs, which refer to easy_install docs, where no "develop mode" either - https://setuptools.readthedocs.io/en/latest/search.html?q=%22develop+mode%22 The problem is that you're not only exposing people to virtualenv, but also to decades of Python packaging problem with keyword like setuptools and easy_install that pip and wheels are trying to solve. It will take days to learn and it is not for Millenials who need immediate gratification to keep them on track (speaking of myself). I mean you guys is the only reason I get back to this. )
Last time I tried to use virtualenv I ended up setting up virtualenvwrapper, and I tell you - there is some big reason why so many virtualenv forks/alternatives exists. So before I edit this text, maybe I can hear arguments why would anyone recommend virtualenv for pip development? The question is two fold:
- Why recommend a tool like
virtualenvat all if pip just works out of the box? - Why recommend old
virtualenvand not more modernvirtualenvwrapperor alternatives?
When you say this is much more reliable - it doesn't sound like an argument to me. Why it is much more reliable? Let's make technical doc technical. It is development doc asking for the whole gory details after all. My argument that you don't need to be exposed to all this complexity, because there is no way you can mess with your system dependencies while developing pip. You may use virtualenv for test run pip install, but that's another story - "How to create virtualenv with custom pip?" where you probably want to keep separate envs for every pip modification to be able to compare state and debug later.
Sorry, I am in a rush again. Can't smile. :)
| .. code-block:: console | ||
|
|
||
| $ .devpip/bin/pip --version | ||
| pip 18.1.dev0 from /home/techtonik/p/pip/src/pip (python 2.7) |
There was a problem hiding this comment.
Minor point: It would be better to show examples using Python 3.x. Python 2 is not something we should be encouraging people to use.
There was a problem hiding this comment.
Yep. Will do. But I will have to use python3 name, because python on Ubuntu 18.04 still points to 2nd version.
There was a problem hiding this comment.
Well, I can not write in another tone. This is the only English I know and even at this level it constantly misses articles. If there is an editor who can quickly skim and do editorial right in GitHub editor - I will appreciate that. Allow edits from maintainers should allow this. In the end it is better if my complete code is edited, but merged, than if I just endlessly argue about why I did this or that change and then gone. I think I spelled out all my argument during the last few hours, and I am not sticking too much to my point of view if somebody is willing to merge an alternative version.
I must say that my final point is that I like when projects can be just run out of the box from source checkout, and I would prefer to launch a process to document all cases where feet shooting can happen rather than fearing that somewhere users silently shoot themselves with a snake in a bathroom. In the end I am able to revert the effects of curse of knowledge to admit that my path till the point that I send hanging patches was far from fast and pleasant. I would say it took me several years to get acquainted with all the gory details, and IMHO it is a luxury that not many people (and not me anymore) can afford nowadays.
| @@ -8,7 +8,55 @@ This document is meant to get you setup to work on pip and to act as a guide and | |||
| reference to the the development setup. If you face any issues during this | |||
| process, please `open an issue`_ about it on the issue tracker. | |||
|
|
|||
| Development tools | |||
| Running Developent Version | |||
| ========================== | |||
There was a problem hiding this comment.
I skipped the intro, because I feel like this part should be in TL;DR section. People who don't needed it can easily skip this section. In fact, I think the auditory of development docs are only two groups of people - newcomers (setup), and occasional contributors who forget things (me).
My goal is to have a quick reference for rebasing and manual testing that my patches still work. For that I need only a single python src/pip line. But I would like to help people coming for an easy or good-first-issue from funnels (marketing) like OpenHatch and upcoming HacktoberFest to have more fun with pip than virtualenv. Just grab someone experienced from Ruby or Node.js background and ask them to run pip from sources. These are the people that I have in mind.
| from the clone directory. This way they do not need to be installed on your | ||
| system. The process of bundling dependencies with a project sources is called | ||
| `vendoring`, but because there is no PEP for that, other Python won't work | ||
| this way and still require `pip` for installation. |
There was a problem hiding this comment.
I said that to warn people that vendoring in pip is probably a hack, and not something supported by language like vendor directories in Go or something approved by community as a general practice. I do this, because Python community is lawful good when it comes to proven things (e.g. nobody do monkey-patching, even if it is possible) and usually devise a PEP to mark something as generally worthy to let people know and allow tools to build around that.
If there is a way for other project to adopt pip-style vendoring for their own project, I would be happy to replace that paragraph with a link to the tutorial, because it is a valuable feature. For me it was a major selling point to contribute to Spyder, SCons and quite a few other projects.
| this way and still require `pip` for installation. | ||
|
|
||
| If you want to practice `virtualenv` development, then `pip` inside can be | ||
| relinked directly to development sources by installing it in |
There was a problem hiding this comment.
I didn't like the wording too, but I want to explain the how --editable option works. The way it is explained by pip is by vague reference to setuptools documentation:
-e, --editable <path/url> Install a project in editable mode (i.e. setuptools "develop mode") from a local
project path or a VCS url.
Which look like undocumented - you won't find find this mode in setuptools docs, which refer to easy_install docs, where no "develop mode" either - https://setuptools.readthedocs.io/en/latest/search.html?q=%22develop+mode%22 The problem is that you're not only exposing people to virtualenv, but also to decades of Python packaging problem with keyword like setuptools and easy_install that pip and wheels are trying to solve. It will take days to learn and it is not for Millenials who need immediate gratification to keep them on track (speaking of myself). I mean you guys is the only reason I get back to this. )
Last time I tried to use virtualenv I ended up setting up virtualenvwrapper, and I tell you - there is some big reason why so many virtualenv forks/alternatives exists. So before I edit this text, maybe I can hear arguments why would anyone recommend virtualenv for pip development? The question is two fold:
- Why recommend a tool like
virtualenvat all if pip just works out of the box? - Why recommend old
virtualenvand not more modernvirtualenvwrapperor alternatives?
When you say this is much more reliable - it doesn't sound like an argument to me. Why it is much more reliable? Let's make technical doc technical. It is development doc asking for the whole gory details after all. My argument that you don't need to be exposed to all this complexity, because there is no way you can mess with your system dependencies while developing pip. You may use virtualenv for test run pip install, but that's another story - "How to create virtualenv with custom pip?" where you probably want to keep separate envs for every pip modification to be able to compare state and debug later.
Sorry, I am in a rush again. Can't smile. :)
| .. code-block:: console | ||
|
|
||
| $ .devpip/bin/pip --version | ||
| pip 18.1.dev0 from /home/techtonik/p/pip/src/pip (python 2.7) |
There was a problem hiding this comment.
Yep. Will do. But I will have to use python3 name, because python on Ubuntu 18.04 still points to 2nd version.
|
Okay. There might be a problem with |
|
Hello! I am an automated bot and I have noticed that this pull request is not currently able to be merged. If you are able to either merge the |
|
Closing this since it's bitrotten. Please file a new PR if there's still interest in this. |
lock
bot
added
the
auto-locked
No description provided.