Revision 2 as of 2020-02-22 03:31:36

Clear message

[Bernard and Pradyun spoke on Feb 6 and Feb 7 to give Bernard an understanding of pip's architecture.]

Feb 6th

Pradyun/Bernard discussion, 6 Feb 2020

Which side of we want to start from? User-facing or broader architecture

At a reasonably high level, what are the moving parts of pip?

Software architecture:

The different parts of pip:

Chunks of work (https://github.com/pypa/pip/milestone/10)

knowing what the key func is

figuring out if the way we printout of the output is useful

making the info message look less like error message to the users

making the error messages more helpful

give them tools to debug the problem

there is a tradeoff here - more error messages, the more complexity you add to the codebase. every detailed message needs to add code and this adds complexity to the codebase

which switches are useful? which are not?

How possible is it for us to map all the pip command journeys' flows? Essentially

Look at how long this is: https://pip.pypa.io/en/stable/reference/pip_install/ (complexity in pip's options)

Feb 7th

Pradyun / Bernard discussion 7 Feb 2020

From Zulip conversation: "UX research on "professional" workflows, closed-source/"industry" usage. That's a base of users that we have very little access to." I'm not sure what routes we can find into that...

pip install / wheel / download

Install is a superset of wheel, which is a superset of download - to draw *very* broad strokes

a chunk of logic for converting what we've downloaded into something we can distribute/install

pip build logic since PEP 517 we've not had a good story for users who want to use sources

Bernard is fairly new to software dev; has experience w/ hardware + electronics; used software mostly as a consumer/user in the past.

Research question (needs better work):

If I'm a dev of a project that I want to publish that on PyPI. PyPI accepts certain types of files - wheels and distro - to go from local dir on my PC (which has all the files) to the state i can upload a built distro to pypi or a company server - that step is is unclear.

The reasons are described in this thread https://discuss.python.org/t/building-distributions-and-drawing-the-platypus/2062 . (Ignore the last 2/3 comments there's a lot of discussion.)

Q for me: what UX work needs to be carried out for this?

pip list vs pip show vs pip search vs pip freeze

These are all similar - they give information about packages

Looked at "search" related issues.

research questions:

Design: ideally the output of this would be to "put all of this functionality into 2 buckets"

review: install a bunch of packages and use the different

search tagged issues: https://github.com/pypa/pip/labels/C%3A%20search

2 patterns that users had issues with: no error messages / errors+info were together or "mysterious" messages

Q to Pradyun: is there a good approach to working out how to improve those messages?

It depends on the context of how to display errors.

We have output that have holes that we want to fill - we need to work out what context needs to be given to the user

Past case of similar issues

Best practices for writing error messages: https://www.nngroup.com/articles/ten-usability-heuristics/

desk research: are there best design guidelines for writing error messages for promoting heuristic #9?

Good outcome: Maintainer guidelines for error messages

Optimistic outcome: Maintainer guidance on identifying areas where we might have such errors

https://wiki.python.org/psf/Pip2020DonorFundedRoadmap

verbosity / output + failure visibility Broader than error messages. is this in/out of scope?

USER STORY

As a user I want to know whats make the display less mysterious

The objective was to redo the output for the pip install command (and connected to wheel / download)

Do we want to interrupt the user in a resolve dep. issue, or print an error at the end?

TODO read this:

Does the structure make sense?

Cascading tasks

Experiment

experiment: take a package with lots of dependencies

how much output do users expect to see? how much output is useful to users?

what is missing from regular output, that's in verbose? (regular = that which is not verbose)

Are there "defined" steps in the complication?

The resolver

resolver this resolves what to download, build, this gives us a state and how to get there.

installing pip install based on the result of the resolver

the nuance of download, install, wheel wheel - command for the user to run, to get wheels for all packages they will use. the user will end up with a lot of wheel files for each of the packages and deps in a dir.

when they do download they'll get wheels and source. Wheels have static metadata, sources do not. (this was the purpose of the proposed metadata 2.0. it also make dep resolv. harder)

This issue is grounded in the lack of metadata we have about packages.

In the process of downloading, pip might end up building wheels as part of the build anyway. in the dep resol loop, you can potentially build a wheel (they have dep information). Not sure where they end up (not so important).

Everything in the dependency resolution process it will build wheels out of those (if its not in the env already), after the resolution

if there is something downlaoded without a wheel, pip wheel will build that, or error out if its not possible.

download - we'll dump this into a dir the user

review the command line usability for automated scripts pfmoore filed it -- https://github.com/pypa/pip/issues/6099

"pip blowsup it usually ends up breaking someones pipeline. a lot of people are going to pinged, probably in the middle of the night."

technical/professional users

I get paid to work on python, everyday. I have specific workflows, I want control on how I build, where I download from, how pip is called

1. scientific

2. corporate

3. distros

4. non-technical/professional users

TODO: reread https://packaging.python.org/glossary/ as a result of today's discussion

Non-professional users will find it easier to find errors/warnings at the end

Bernard to make a branch for this work, make it and test it. Maybe work with Pradyun on the messaging.

Unable to view page? See the FrontPage for instructions.