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

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?

No, I don't. :(

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

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.

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

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

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

OK.

I would love a short example here.

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

That's fine considering you link to a sample.

The readme should also contain licensing information.

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.

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

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.

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?

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.

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.

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.

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.

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

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.

OK, I can fix this up.

drop the variant here, as GFM is the default.

OK, I'll change this.

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.

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

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

OK, I'll change this.

OK, I can fix this up.