Expand reference and user documentation

• .pypirc - link to the comprehensive documentation at https://docs.python.org/3/distutils/packageindex.html#pypirc and say, for instance, your .pypirc file needs a [pypi] section, and per #118, the documentation should discuss how you can choose to use .pypirc to store the URL of a repo even if you don’t want to store credentials.

• #277 is where we are specifically figuring out what documentation to add about keyring usage, which figures into pypa/python-packaging-user-guide#297 for the Python Packaging User Guide. I want to both make sure that we have, or link to, comprehensive .pypirc guidance, AND encourage folks to use keyring instead.

• improve twine -h / twine --help invocation (right now you have to invoke as twine upload -h and the twine -h upload error message is misleading)

• improve command help/usage annotations for twine upload to explain that you should upload dist/*

• address pypa/python-packaging-user-guide#145 and this Twitter conversation by adding a “use Test PyPI” line to the Usage section of the README

• add “when to use this versus when to use flit/zest.releaser” to README

• OS-specific troubleshooting tips, e.g., https://github.com/pypa/twine/issues/274#issuecomment-337340465 troubleshooting tip for Mac users running with SIP enabled

• a maintainer checklist for making new releases (see #306)

• improve command help/usage annotations/README for twine upload to add instructions for adding a detached GPG signature & uploading it

[brainwane]

I’m a newish Twine maintainer. Thanks for the suggestions for improvement!

A status update:

In July 2017, uploading to pypi.python.org stopped, and now package maintainers can only upload to the new PyPI, pypi.org. Warehouse, the codebase behind the new PyPI, is available as a pre-production site at https://pypi.org, and I’m one of the people working on it. We’re making steady progress on the developer roadmap thanks to funding from Mozilla’s Open Source Support Program, and it’s on its way to fully replacing the legacy PyPI site, I believe, this year. We’re currently seeking feedback from package maintainers, including via several IRC livechats/office hours this week, about what does or doesn’t work for you in the new interface, and in the next few weeks we’ll be doing so with the wider Python developer community.

I’m working on releasing Twine 1.10.0 in the next few days.

We’ve improved Twine user (and developer) documentation a lot in the past couple months – see http://twine.readthedocs.io/ which now works, including the changelog. And the Python Packaging User Guide has a lot more material than it used to about .pypirc files and about packaging and uploading with Twine more generally – see https://packaging.python.org/tutorials/distributing-packages/?highlight=pypirc , https://packaging.python.org/guides/migrating-to-pypi-org/?highlight=pypirc , and https://packaging.python.org/guides/using-testpypi/?highlight=pypirc .

Clearly we need more reference documentation and user help docs, on Twine behavior, .pypirc (although perhaps a comprehensive .pypirc guide should live at https://packaging.python.org ), and Twine internals. I’d welcome issues and pull requests.

I’m editing the original post at the top of this thread with a TODO list.

[bhrutledge]

Re: .pypirc and keyring, I added some research and possible next steps to https://github.com/pypa/packaging.python.org/issues/297#issuecomment-576409783. See also https://github.com/pypa/twine/issues/118, https://github.com/pypa/twine/pull/340, https://github.com/pypa/twine/issues/216, and https://github.com/pypa/twine/issues/324.

I’m tempted to break this issue up into discrete, actionable issues.