Skip to content
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

Add README guide #461

Merged
merged 7 commits into from
Apr 27, 2018
Merged

Add README guide #461

merged 7 commits into from
Apr 27, 2018

Conversation

ddbeck
Copy link
Contributor

@ddbeck ddbeck commented Mar 31, 2018

This adds some guidelines for writing and setting metadata for READMEs that will play nicely with PyPI. This should cover a lot of the things discussed in #210.

* Markdown (`GitHub Flavored Markdown <https://github.github.com/gfm/>`_ by default,
or `CommonMark <http://commonmark.org/>`_)

It's customary to save your README file in the root of your project, in the same directory as your ``setup.py`` file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think saying "setup.py or pyproject.toml" here would be nice.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good idea, @pradyunsg ! I'll rework this a little to mention pyproject.toml.

Even better though would be to include a first-class pyproject.toml example. Do you know of any projects I could look at that specify a README and markup in their pyproject.toml?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I don't. :(

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we want to hold off on pushing pyproject.toml too heavily until there's a version of pip available with initial PEP 517 support for pluggable build backends.

Then we can add a sample flit project with only pyproject.toml (assuming flit supports getting its settings from there).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, well, I still reworked things to leave room for other ways of specifying—it shouldn't require too much rewriting to add pyproject.toml when it becomes a practical option.

Copy link
Member

@theacodes theacodes left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for doing this, @ddbeck

----------------------

README files are often named ``README`` or ``README.txt`` for plain-text READMEs,
or :samp:`README.{extension}` where *extension* indicates a markup language
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not just enumerate all of them? We only support 3 different content types README.txt, README.md, and README.rst.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because other formats exist even if we don't support them yet?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is written as if in the abstract. This guide should focus on the actual:

READMEs for Python projects are generally named ``README``, ``README.rst``, or ``README.md``.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK.

* what your project is and how it can help them
* how to install or use your project
* where to go to contribute or get help

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would love a short example here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I worry that even a short example would be long enough to dominate the page. I'd rather link to resources and examples elsewhere.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's fine considering you link to a sample.


* what your project is and how it can help them
* how to install or use your project
* where to go to contribute or get help
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The readme should also contain licensing information.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to go overboard about details of README content and I'm not sure there's a brief way to describe describing a license in a README file.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, this is what the license classifiers and the License metadata field are for.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There absolutely is a brief way of describing it:

* the name of the license your project is under.

See here for example.

It's so incredibly critical that this information is in the project description as many packages can omit the license metadata.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Naming a license is not the same as describing it and merely naming a license in the README file is a poor approach. The title of a license alone only helps readers in narrow circumstances: they know what the license is already and the author has fully identified that license.

For your example, "Apache 2.0" doesn't help a reader like me. I don't know, even in the most general terms, what the license grants me or obligates me to do. But I'm lucky in that "Apache 2.0" at least distinguishes it from other licenses; you'd be surprised how often people think "GPL" or "BSD" without additional qualifiers is their software's license.

Writing helpfully about licenses is doable. I think the way Creative Commons summarizes licenses as "free to… under the following terms…" is a great approach. It's more involved than a bullet point, though.

But honestly, if it's so incredibly critical then why isn't the licensing metadata required?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your comment @jonparrott and your patience while I got back to you on this.

To go meta for a moment, you asked why there was push back here. I can't speak for anyone else, but I put a lot of care into this doc and I had good reasons for pretty much everything I wrote from the outset. And I have bit of a personal attachment to the topic generally, since "Daniel cares a lot about READMEs" seems to be my personal brand of late. What can I say? I care about this.

Now for the actual issue: I see where you're coming from. I agree with you that licensing is important. But I don't think that providing licensing information to users, in isolation, is a primary goal of README files. Nor do I think licensing represents a major problem for README authors: when I surveyed READMEs for a conference talk, I found that remembering to name your project and link to the repo or homepage is a more significant and pervasive failure on the part of README authors than licensing. 😬

But I'm also uncomfortable with implying that naming a license is significant and meaningful (by itself, outside a bigger discussion on software licensing). I believe that approach contributes to a ritualistic view of copyright (and law broadly) in which people believe magic words will bind others' actions. It feels like a sort of anti-civics lesson.

I have to say though, I really like this general idea of licensing in-depth. I would love to see a doc on how to properly license, top to bottom, a Python package (and maybe even address some Python specific examples—like what's the relationship between import somelib and its license? I wish I knew!). I think my ideal outcome would be to link to that page from this one, rather than trying to cover a tiny slice of it here.

Copy link
Member

@theacodes theacodes Apr 12, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would love to see a doc on how to properly license, top to bottom, a Python package (and maybe even address some Python specific examples—like what's the relationship between import somelib and its license? I wish I knew!). I think my ideal outcome would be to link to that page from this one, rather than trying to cover a tiny slice of it here.

I would love that, want to file a separate issue?


Back to the topic at hand - Let me rephrase your argument against adding this as an argument against adding one of the items you already have in this list:

But I don't think that providing contribution information to users, in isolation, is a primary goal of README files. Nor do I think accepting contributions represents a major problem for README authors.

My argument is this: either this section should contain just the bare minimum which you identified through survey as just "the project name and homepage" or we should amend this list to include the name of the license. If it's going to be an arbitrary list of common items, license should be there. If it's going to be the bare minimum, then none of these other things should be there.

Copy link
Member

@theacodes theacodes Apr 12, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also want to offer a reasonable bridge here: We could go the bare minimum route here and do something to this effect:

Your README should at minimum contain your project's name and a link to your project's homepage where users can find out more information. For a information on writing a more comprehensive project README, we recommend using readme-checklist.

Your README checklist project more than satisfies my desires in terms of documenting the license and I am more than happy to promote it here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And of course, re-reading the changeset I see that you already link to it, which makes me more in favor of the minimalist approach.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jonparrott please don't change my words to say something I would not have argued and then put it in a block quote. This feels a half step removed from the mocking SpongeBob meme.

Anyway, I'm chaffing a bit at the suggestion that my recommendations were arbitrary, so I'm pushing a change to drop the README content section entirely. Accept the PR or don't, but I'm done being needled over this.

For example, to set these values in a package's :file:`setup.py` file,
use ``setup()``'s ``long_description`` and ``long_description_content_type``.

Set the value of ``long_description`` to the contents of the README file itself.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: make it clear not to use the readme file name:

Set the value of ``long_description`` to the contents of the README file itself, not to the file name of the README file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I can fix this up.

name='an_example_package',
# other arguments omitted
long_description=long_description,
long_description_content_type='text/markdown; variant=gfm'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

drop the variant here, as GFM is the default.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I'll change this.

Copy link
Contributor Author

@ddbeck ddbeck left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback, @jonparrott. Some comments, and some changes forthcoming.


* what your project is and how it can help them
* how to install or use your project
* where to go to contribute or get help
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to go overboard about details of README content and I'm not sure there's a brief way to describe describing a license in a README file.

----------------------

README files are often named ``README`` or ``README.txt`` for plain-text READMEs,
or :samp:`README.{extension}` where *extension* indicates a markup language
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because other formats exist even if we don't support them yet?

* what your project is and how it can help them
* how to install or use your project
* where to go to contribute or get help

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I worry that even a short example would be long enough to dominate the page. I'd rather link to resources and examples elsewhere.

name='an_example_package',
# other arguments omitted
long_description=long_description,
long_description_content_type='text/markdown; variant=gfm'
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I'll change this.

For example, to set these values in a package's :file:`setup.py` file,
use ``setup()``'s ``long_description`` and ``long_description_content_type``.

Set the value of ``long_description`` to the contents of the README file itself.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I can fix this up.

@theacodes
Copy link
Member

FYI: chatted with @ddbeck over email and I'm cool with these changes. Merging. :)

Thanks, @ddbeck!

@theacodes theacodes merged commit 4ef7c91 into pypa:master Apr 27, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants