-
Notifications
You must be signed in to change notification settings - Fork 1k
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
Add README guide #461
Conversation
* 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, I don't. :(
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this 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 |
There was a problem hiding this comment.
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
.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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``.
There was a problem hiding this comment.
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 | ||
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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' |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this 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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 | ||
|
There was a problem hiding this comment.
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' |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
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.