Use standard-readme for all Readmes

[RichardLitt]

I would like to enforce standard-readme throughout IPFS. You can look at the spec on the main Standard-Readme README, and look at the IPFS subset I want to lint for here, or below:

Please give a thumbs up to this issue or open issues on standard-readme if you want or do not want specific sections. Or, discuss below.

These requirements are only for the IPFS organization. They are included here because some people may still be curious how IPFS and Standard-Readme are related. Since this work is supported and will be used by the IPFS organization, they are relevant here, too, I think.

• Buttons
  • All repos: irc, made by Protocol Labs, IPFS project
  • Language repos: langdoc references, code style, dependencies, coverage
  • Travis
  • CI
  • Discussion repos
• Contribute banner with link to global contribute.md
• Link to questions
• LICENSE file
• PATENTS file
• Contribute.md file

[dignifiedquire]

Why do we have to have a PATENTS file? (A link to previous discussion is enough if this was already discussed somewhere else)

[hackergrrl]

Heya Richard. Some aggressive grilling on many of your items: 😀 I'm being aggressive on asking for concrete justifications on these only because the formula (work to get 1 repo on standard) x (# of IPFS repos) is so large. Having to change any aspect of this later ends up being multiplied across all of these repos -- it's better in my experience -- to start with less (only the things you 100% definitely need) and add more later as justification becomes very apparent. Without further ado:

1. What value does a IPFS button have? These'll be in the IPFS org, so ownership is already clear.
2. What value does a Protocol Labs button have? This doesn't affect contributors, and anyone who it would affect would already know about this relationship.
3. What is "langdoc references"?
4. Is "Travis" a subset of "CI"?
5. What does "discussion repos" refer to in this context?
6. What does "link to questions" refer to in this context?
7. Do we legally require a LICENSE file, or is mentioning it in the README sufficient? The latter would be preferred, since it reduces the amount of files in the repo root dir (less noise), and one less place to make a mistake (accidentally mismatch license in repo /w one in LICENSE file).
8. We're already adding a contribute banner and link to our contribution guidelines -- do we need a contribute.md file as well? Is there information in one that isn't in the other? Can we deduplicate?

[daviddias]

One good way to get very concrete feedback is to submit 2 to 3 PR to projects inside the IPFS community that are lead by different people (2 to 3 projects per Lead maintainer), because as soon as you do that, each project maintainer will give a very throughout review if the readme matches what are their expectations.

[RichardLitt]

I'm being aggressive on asking for concrete justifications on these only because the formula (work to get 1 repo on standard) x (# of IPFS repos) is so large. Having to change any aspect of this later ends up being multiplied across all of these repos -- it's better in my experience -- to start with less (only the things you 100% definitely need) and add more later as justification becomes very apparent.

I agree with this. Thank you.

1. What value does a IPFS button have? These'll be in the IPFS org, so ownership is already clear.

Not all IPFS repositories are in the IPFS organization. We should really be applying this standard to anything developed under IPFS purview - libp2p and Orbit might also apply. But then, they shouldn't be tagged IPFS, I guess.

But branding is also important. I think the redundancy is OK. When filecoin and the like come out, we can re-evaluate this - for now, IPFS is the main name people know for this project, and we should reference that. Also, repos exist independantly of the organization - for instance, when cloned and in a local filesystem. There should be some note in the README about the organization.

Suggestion: Keep this.

1. What value does a Protocol Labs button have? This doesn't affect contributors, and anyone who it would affect would already know about this relationship.

Branding, really. It's another entry point, says where these things came from. Name recognition.

Suggestion: Keep this.

1. What is "langdoc references"?

Link back to js-contribute.md in community, or go-contribute.md. Language-relevant contribution guidelines.

Suggestion: Keep this.

1. Is "Travis" a subset of "CI"?

Yes. This label only applies when we actually have CI for a repo - obviously this doesn't happen for all of them.

Suggestion: Make optional.

1. What does "discussion repos" refer to in this context?

Something like https://github.com/ipfs/notes - repos which have no or minimal code in them, where all of the discussion happens in the GitHub issues.

Suggestion: Use a subset of standard-readme where there is no 'install' or 'usage' section.

1. What does "link to questions" refer to in this context?

Link to the issues. This happens in the Contribute.

1. Do we legally require a LICENSE file, or is mentioning it in the README sufficient? The latter would be preferred, since it reduces the amount of files in the repo root dir (less noise), and one less place to make a mistake (accidentally mismatch license in repo /w one in LICENSE file).

I believe we legally do. This is not a question I know the answer to, and I haven't seen conclusive proof either way. However, I think that the redundancy is important - licensing is something that should be clear from the README (the first entry point into a module), because it is relevant to contributors. I think it is more important to have it here than to worry about noise or the chance of a mistake.

Suggestion: Keep this.

1. We're already adding a contribute banner and link to our contribution guidelines -- do we need a contribute.md file as well? Is there information in one that isn't in the other? Can we deduplicate?

No, we don't need a contribute.md for each repo - a contribute section is enough.

Suggestion: Reword.

One good way to get very concrete feedback is to submit 2 to 3 PR to projects inside the IPFS community that are lead by different people (2 to 3 projects per Lead maintainer), because as soon as you do that, each project maintainer will give a very throughout review if the readme matches what are their expectations.

Good idea. Doing that now.

[Kubuxu]

Separate license files are important, if not from the pure law perspective then from the user and packaging perspective. If project has license file and I want to package the project (for example to AUR), I will copy the file to the license folder of your system. If it has no such file then I have to dig through README.

Also please, include name of the license in your LICENSE files. Especially if it is some of the more of a unusual license or BSD (there are two commonly used BSD variants and one more used early).

I might have gone a bit of topic

Also there is a benefit for using CONTRIBUTING.md file, GH will show notice about that file while creating issues and PRs: https://github.com/blog/1184-contributing-guidelines

[RichardLitt]

Agreed on separate license file being mandatory.

Not agreed on contribute file being mandatory for all repos - some can point to community just fine, or just have a small section (discussion repos). Good point about the notice for GitHub, though. Lean towards using it whenever possible?

[RichardLitt]

This is a tracking comment for all IPFS repos. Add links and checks here as appropriate.

• apps
• archive-format
• archives
• awesome-ipfs
• bitswap-ml
• blockchain-data
• blog
• community
• connections-globe
• container-demos
• dataviz
• dir-index-html
• distributions
• dnslink-deploy
• examples
• faq
• file-browser
• fs-repo-migrations
• fs-stress-test
• glossary
• go-blocks
• go-commands
• go-ipfs
• go-ipfs-api
• go-ipfs-gateway
• go-ipfs-util
• go-ipld
• go-iprs
• go-key
• go-libp2p
• go-libp2p-crypto
• go-libp2p-loggables
• go-libp2p-peer
• go-libp2p-peerstore
• go-libp2p-pubsub
• go-libp2p-secio
• go-libp2p-transport
• go-log
• http-api-spec
• infrastructure
• install-go-ipfs
• interface-ipfs-core
• ipfs
• ipfs-blob-store
• ipfs-geoip
• ipfs-hubot
• ipfs-interop
• ipfs-js-defaults
• ipfs-npm
• ipfs-update
• ipfs-web-app
• ipfs.js
• ipget
• ipld-examples
• ipld.io
• java-ipfs-api
• js-ipfs
• js-ipfs-api
• js-ipfs-bitswap
• js-ipfs-block
• js-ipfs-block-service
• js-ipfs-examples
• js-ipfs-ipld
• js-ipfs-path
• js-ipfs-repo
• js-ipfs-unixfs
• js-ipfs-unixfs-engine
• js-ipfsd-ctl
• js-ipld
• js-ipld-cli
• js-libp2p-crypto
• js-libp2p-ipfs
• js-libp2p-ipfs-browser
• js-libp2p-secio
• logo
• newsletter
• notes
• npm-go-ipfs
• ops-requests
• paperhub
• papers
• pm
• POST
• project-repos
• py-ipfs
• py-ipfs-api
• refs
• refs-denylists-dmca
• refs-solarnet-storage
• scala-ipfs-api
• specs
• starlog
• station
• support
• swift-ipfs-api
• website
• webui

[RichardLitt]

What ought we to do about forks? For instance, astralboot is forked from @zignig's repo. Should I PR his README, too?

[RichardLitt]

This is relevant. Feedback would be great: RichardLitt/standard-readme#20

[RichardLitt]

I would consider this now done. Anyone else want to weigh in?