Repository creation and readme conformity guidelines

[RichardLitt]

We should have a guide for creating repositories, and for standardizing READMEs for all IPFS repositories.

Each repository should have:

• A clear description in the GitHub description field.
• A clear description (which can be longer) in the README.
• A license - potentially MIT, or CC0, depending on the type of organization. Having different licenses is OK.
• A contribute section in the Readme for discussion repositories, or a contribute.md if there are more specialized instructions (for instance, language styles, which should link to a language contribution guide in this repository.
• A usage section (if appropriate)
• A link to places to ask questions - this can be ipfs/community, too.
• Buttons!!!

What do you think are necessary? I'll open a PR after some discussion.

[RichardLitt]

Also:

• Travis link
• CI links

Some of these should be mentioned both in the README standard requirements, and as part of a "setup a new repo" section. The setup section should include linking to https://github.com/ipfs/ipfs/blob/master/project-directory.md.

[jbenet]

👍 x 💯 ^ 💯

this is great. @RichardLitt we should turn this into a script we can run that uses tap/tape to check all the repos and returns an error if they're failed. we can then put that on a throwaway repo with travis-ci and we can rerun the travis build / push a commit to run tests that check all the repos are good :D

[jbenet]

cc @diasdavid as he cares about this too

[jbenet]

for the buttons, maybe we can make lists of buttons to include:

• what to include in ALL repos
• what to include in each lang (e.g. node, go, etc)
• what to include in community / docs repos

and we should have an "IPFS Project" banner.

• i still love: https://github.com/jbenet/contribute-ipfs-gif/raw/master/img/contribute.gif but it can be something more professional looking if people dislike it.

[daviddias]

YES, thank you :D

@jbenet can we have like a full readme wide length 'contribute to IPFS'?

The 'contribute to IPFS' section could also have an 'endeavours' section like : libp2p, go-ipfs, offline web components, starship, etc. So that people had a clear way to understand all of the things we are doing and which they might want the most to contribute :)

[RichardLitt]

Happy to turn this into a script. I guess I'll start a new repository to do that.

I'm sorry, but if by "more professional" you mean more likely to be used by these people:

Then I am OK with something else, otherwise that banner is already perfect. I don't think we need a Readme-width one, those are arbitrary based on window sizes anyway.

Buttons to include:

All repos

Language-specific repositories

Community / Docs / Discussion repos

• Some sort of "See the Issues" thing?

[daviddias]

Why have and ? (other than the blue one is already there and the green one is new)

I would like, if we may, to avoid using green+yellow+red for informative stuff as those colors have associated values with CI mechanisms

[RichardLitt]

Good point. Let's stick with blue. Editing comment.

[amstocker]

@jbenet I am a huge fan of that contribute to ipfs badge! Professionalism is boring :)

[RichardLitt]

Note: We also need to include a section for how to make community repositories.

[jbenet]

THe contribute to ipfs banner should link to a short doc on how to help, with links to more areas

[daviddias]

Is this done as something we can follow now? @RichardLitt ?

[RichardLitt]

@diasdavid No. Working on it; not sure how to best parse READMEs, I've been looking for tools that should enable us to do this well. Ongoing work will be done here: https://github.com/ipfs/ipfs-readme-standard

[RichardLitt]

Another thing to add, from @diasdavid:

btw, protip: use npm-release like npm release patch, so that it creates a release with a tag and so on. @RichardLitt, you might want to add this to the JS boilarplate for our modules :)