Roadmap for pip resolver and UX work in 2020

Thanks to the Chan Zuckerberg Initiative and Mozilla's Open Source Support program, the PackagingWG is receiving funding to finish pip's dependency resolver and improve pip's user experience.

Key people

Contractors working on this project will be

• Two Python developers being hired via Python Software Foundation RfP, to be announced December 2019

• User experience research and design consultancy Simply Secure

• Project manager: Sumana Harihareswara of Changeset Consulting

Work summary

We're partway through a next-generation rewrite of the dependency resolver within pip, Python's package download and installation tool. The project ran into massive technical debt, but the refactoring is nearly finished and prototype functionality is in alpha now. Many improvements and installation and dependency issues for Python users, conda/Anaconda, and other platforms are blocked awaiting this feature.

Also, pip's user experience needs to become more consistent across features, fit the user's mental model better, reduce unintended data loss, and provide better error messages and prompts, logs, output, and reporting.

Two developers, a UX design/research consultancy, and a project manager will execute a three-phase plan to support user experience, communications/publicity, and testing work (including developing robust testing and continuous integration infrastructure) on the resolver, as well as core feature development and review.

Initially, as developers come up to speed on pip and work on finishing refactoring the build logic within pip, UX experts will study the command line packaging/distribution environment, run user tests, and develop robust user journeys/concept maps.

Second, the contractors will work together on implementing the resolver. The developers will write tests, improve CI, build test infrastructure, introduce new abstractions and fix bugs found in alpha testing, collaborate with downstreams and users about config flags and transition schedules, and so on. The UX experts will improve command-line UX (such as in-CLI help and error messages, and specific commands and names of flags), and improve the pip user guide.

Finally, one contract developer will maintain the pip repository by triaging bugs and reviewing pull requests (releasing bottlenecks), and the UX expert will train maintainers in CLI UX design principles and write UX guidelines for the project.

Throughout, a project manager will find and communicate with stakeholders and testers, and with the funder.

Detailed work plan

Exists in other documents; reformatting and copying to this page is in progress.

Phase I (Foundational work, early 2020)

Developers' onboarding and initial work

See RFP.

UX onboarding and initial work

• Read, view, and process the voluminous existing information on pip user confusion (such as the "Improve UX" milestone https://github.com/pypa/pip/milestone/10, "Print Better Error Messages" milestone https://github.com/pypa/pip/milestone/25, Stack Overflow questions about pip, and unofficial blog posts and articles such as "The Python Packaging Ecosystem" https://www.curiousefficiency.org/posts/2016/09/python-packaging-ecosystem.html)

• Perform user interviews and testing, and writeups (covering pip). These will be organized similarly to how the grant-funded PyPI team's UX researcher/designer organized user interviews and user tests (see https://whoisnicoleharris.com/2018/03/13/user-testing-warehouse.html, https://whoisnicoleharris.com/2018/07/22/pypi-user-research.html, and https://github.com/pypa/warehouse/issues/6173). We will recruit diverse users who have different skill levels, come from industry, academia, and more, are diverse across gender, ethnicity, and age, and have different computing environments. Outcomes: greater systematic understandings of users' workflows, mental models, and current priorities for fixing issues, to feed into developer documentation.

• Develop user journey maps & workflows

Phase II (Resolver work, ~March-June 2020)

Developers

See RFP.

UX

• Working with maintainers to write documentation and help messages, and to design resolver user experience

Phase III (Maintenance and Sustainability work, June-December 2020)

Developer

• Keep up with the pip code and issue review queue for 10 hours per week, thus releasing a key bottleneck and enabling existing maintainers to make progress on key architectural features
• Help new contributors develop into continuing contributors
• Help existing contributors grow into co-maintainers

UX

• Interview users, run tests, and writeup (covering resolver and expanding research scope). These will be organized similarly to the research in the first phase, but will measure user experience improvements from the new resolver, and will allow the researcher to expand their research. Scope to, for instance, issues involving conda, virtualenvs, and other package managers. Outcomes: greater user understandings, as above, and assessment of the UX improvements in the new resolver.
• Update workflows, expand user journeys, and develop checklist for developing new features
• Develop templates for UI bugs, commands, error messages, output, documentation, and configuration files

• Teach other pip developers UX practices per https://simplysecure.org/what-we-do/user-research/

• Develop list of people/organizations who can participate in UX testing