document how a python project should document installing itself

[glyph]

Right now, many many projects on PyPI document their install process as sudo pip install. This is (obviously, I hope) suboptimal.

How should projects document their installation process? It's tempting to say "just pip install", but this falls apart if:

1. the user doesn't have a C compiler, but the project has a C extension
2. the user doesn't have the right version of a C compiler (for example: matching up Windows compiler versions to Python versions)
3. the project has native dependencies outside their platform's base installation package (libffi, libssl, libcrypto being popular ones, but more esoteric libraries like gtk, libpng, imagemagick, and so on also cause interesting issues)
4. the user isn't root, doesn't have an awesome pip configuration and doesn't know about virtualenv

There's also the issue that if you use platform packages, you get automatic security updates (at least sometimes) but there doesn't appear to be any generally acknowledged "best practices" for getting security updates with pip. There isn't even any standard security-update-notification mechanism I'm aware of. Is it even possible to get PyPI to send you an email when new versions of a thing are released?

However, putting a dissertation into every project's documentation about how to install pip, virtualenv, apt, yum, nuget, homebrew, ebuild, nix, and seven other package managers is unlikely to result in a positive user experience.

Getting to the point where projects no longer have mutually contradictory documentation that provides a good experience is likely to be a long slog, but it seems like this guide should provide a starting point that projects can begin linking to so that users can get some quickstart instructions which work almost all of the time, and can have a good central reading list for understanding the subtleties associated with different ways that packages can be installed.

[qwcode]

noted. good points.

a new section in the "Tutorial on Packaging and Distributing Projects" is warranted that explains what sections in the "Tutorial on Installing Packages" to link to, which will entail some work though because it doesn't currently discuss compiling extensions or fulfilling external dependencies from the OS.

[glyph]

@qwcode - thanks.

It's also important to really whittle this down to the essentials so that people can get up and running quickly. Remember that we're competing with JavaScript in some sense here, whose installation story is "put this file on your hard disk and open it in your web browser" :).

[ncoghlan]

Part of the problem is that there isn't a universally good answer, since it depends on what you're doing, and what you're aiming to integrate with. It's also where the needs of language-specific cross-platform development and language-independent platform-specific operations management come into sharp conflict (https://fedoraproject.org/wiki/Env_and_Stacks/Projects/UserLevelPackageManagement has some more thoughts on that from the platform provider side of things).

I think the situation is slightly happier on the update notifications side of things. https://release-monitoring.org/about describes the language independent pluggable approach Fedora is migrating to (from https://fedoraproject.org/wiki/Upstream_release_monitoring), and I believe Debian are moving in that direction as well. Publishing all PyPI updates through there as a matter of course is something that could be worth doing (if both @dstufft and @r1chardj0n3s and the Anitya developers are amenable to the idea).

https://requires.io/ appears to be a decent Python specific change tracking service.

For security updates specifically, I've had some good conversations with the folks behind http://victi.ms/. While that's primarily focused on Java vulnerabilities right now, the intention has long been to expand it to track CVE's for multiple languages.

[glyph]

@ncoghlan - I'm aware that there isn't a universally good answer. But there should at least be a couple of defaults which will be reasonable for many projects. Right now there is lots of copying and pasting going on between projects, each variant with its own unexplained subtleties. Instead, there should be a central resource for this kind of guidance which can be updated as the deployment ecosystem changes.

[ncoghlan]

There was a placeholder for platform specific guidance under advanced topics, but it was one of the victims of Marcus's recent cull of skeleton pages - we hadn't had any volunteers to fill it in, so it was just headings with blank sections and/or rough bullet points.

[glyph]

I wouldn't advocate for a placeholder page to be added back, this issue should just remain open until such time as someone can write a full version :)