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

Conversation

Projects
None yet
5 participants
@ddbeck
Contributor

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.

This comment has been minimized.

@pradyunsg

pradyunsg Apr 1, 2018

Member

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

This comment has been minimized.

@ddbeck

ddbeck Apr 1, 2018

Contributor

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?

This comment has been minimized.

@pradyunsg

pradyunsg Apr 1, 2018

Member

No, I don't. :(

This comment has been minimized.

@ncoghlan

ncoghlan Apr 1, 2018

Member

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).

This comment has been minimized.

@ddbeck

ddbeck Apr 1, 2018

Contributor

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.

@theacodes

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

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

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

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

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``.

This comment has been minimized.

@ddbeck

ddbeck Apr 3, 2018

Contributor

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

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

I would love a short example here.

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

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

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

The readme should also contain licensing information.

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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.

This comment has been minimized.

@di

di Apr 2, 2018

Member

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

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

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.

This comment has been minimized.

@ddbeck

ddbeck Apr 3, 2018

Contributor

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?

This comment has been minimized.

@ddbeck

ddbeck Apr 11, 2018

Contributor

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.

This comment has been minimized.

@theacodes

theacodes Apr 12, 2018

Member

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.

This comment has been minimized.

@theacodes

theacodes Apr 12, 2018

Member

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.

This comment has been minimized.

@theacodes

theacodes Apr 12, 2018

Member

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.

This comment has been minimized.

@ddbeck

ddbeck Apr 12, 2018

Contributor

@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.

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

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.

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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'

This comment has been minimized.

@theacodes

theacodes Apr 2, 2018

Member

drop the variant here, as GFM is the default.

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

OK, I'll change this.

@ddbeck

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

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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'

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

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.

This comment has been minimized.

@ddbeck

ddbeck Apr 2, 2018

Contributor

OK, I can fix this up.

ddbeck and others added some commits Apr 2, 2018

@theacodes

This comment has been minimized.

Member

theacodes commented Apr 27, 2018

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

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment