Skip to content

Add note about requirements for Markdown descriptions #481

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
di opened this issue Apr 28, 2018 · 6 comments
Closed

Add note about requirements for Markdown descriptions #481

di opened this issue Apr 28, 2018 · 6 comments
Labels
good first issue type: enhancement A self-contained enhancement or new feature

Comments

@di
Copy link
Member

di commented Apr 28, 2018

A lot of users are getting bit when first trying to publish when their first Markdown description because various tools they're using are out of date:

When we're talking about long_description_content_type or Description-Content-Type in this guide, we should probably add a note or caveat about requiring the following versions for it to work:

  • setuptools>=38.6.0
  • wheel>=0.31.0
  • twine>=1.11.0
@pgadige
Copy link
Contributor

pgadige commented May 31, 2018

I'm working on this.
I think I'll add a note saying that

When you are writing your project's description using Markdown on PyPI, ensure that the versions of the following are used:

  • setuptools>=38.6.0
  • wheel>=0.31.0
  • twine>=1.11.0

before the box with the example code.
Could you please review the content that should go into the note box?
@di and @theacodes, may I know your thoughts about this one?
Thank you!

@di
Copy link
Member Author

di commented May 31, 2018

Given the confusion with pypi/warehouse#4099, we should probably also indicate that the upload must be performed with twine, and not with python setup.py upload.

We could also provide a helpful command to run to ensure all versions are up to date, like pip install -U setuptools wheel twine.

@jarekwg
Copy link

jarekwg commented May 31, 2018

^ Yes please!
Alongside version requirements, the actual commands should be clearly listed:

python setup.py bdist_wheel
twine upload dist/<new_package_name>

Took me a silly amount of stack overflow digging to figure this out..

@pgadige
Copy link
Contributor

pgadige commented Jun 12, 2018

I drafted a concise note including the above details:

If you're using GitHub flavored Markdown to write a project's description on PyPI, ensure you update the following tools:

 `python3 -m pip install --user --upgrade setuptools wheel twine`

The preferred versions of the tools:

  • setuptools>=38.6.0
  • wheel>=0.31.0
  • twine>=1.11.0

It's recommended you use twine to upload the project's distribution packages:

`twine upload dist/*`

Could you please review the content and the structure of the draft, @di and @theacodes ?
I appreciate your feedback and suggestions.

@theacodes
Copy link
Member

Looks good enough to start with, send a PR?

@pgadige
Copy link
Contributor

pgadige commented Jun 13, 2018

@theacodes and @di, I added a note at what I thought would be an appropriate place in the existing doc. I'll appreciate your feedback, suggestions and corrections to be made. Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue type: enhancement A self-contained enhancement or new feature
Projects
None yet
Development

No branches or pull requests

4 participants