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

[harlantwood]

Related: ipfs/infra#25

Ideally, IMO, we have a matrix of projects, say one project per row. Colums include:

• CI passing for that project
• each of the readme items we care about above
• whatever else we care about

Then you can take in the whole matrix ... If anything is not red or orange something needs help.

[harlantwood]

We should probably also choose Travis or Circle and standardize on just one. I have switched my current preference to Travis for node projects at least.

[daviddias]

@harlantwood I believe we have been using both for a while because some of the times we capture different bugs in one of the two. (CI your CI :P)

[harlantwood]

@diasdavid perhaps we standardize on "both" then?

[dignifiedquire]

I would suggest to make it either or. I'm seeing the benefit of having some project use one or the other, but not having both running.

[jbenet]

Test infrastructure is subtly different and one will sometimes reveal problems the other does not. We've already seen this in go-ipfs. Please use both.

—
Sent from Mailbox

On Sat, Nov 7, 2015 at 5:56 PM, Friedel Ziegelmayer
[email protected] wrote:

I would suggest to make it either or. I'm seeing the benefit of having some project use one or the other, but not having both running.

Reply to this email directly or view it on GitHub:
#45 (comment)

[jbenet]

(With testing, the more -- easy to use and working systems -- the better)

—
Sent from Mailbox

On Sat, Nov 7, 2015 at 7:51 PM, Juan Batiz-Benet [email protected] wrote:

Test infrastructure is subtly different and one will sometimes reveal problems the other does not. We've already seen this in go-ipfs. Please use both.
—
Sent from Mailbox
On Sat, Nov 7, 2015 at 5:56 PM, Friedel Ziegelmayer
[email protected] wrote:

I would suggest to make it either or. I'm seeing the benefit of having some project use one or the other, but not having both running.

Reply to this email directly or view it on GitHub:
#45 (comment)

[harlantwood]

Regarding the IPFS banner:

I'd like to have a canonical URL and markdown fragment that is common across all repos, to make it easy to check all repos in ipfs-inactive/project-repos#1.

Of course the cool thing would be to serve the image from IPFS itself:

https://ipfs.io/ipfs/QmV4JU8mw3TR7kDtwkkevXm6KyQFAbSJWZKoto8NXe8iGR

This works fine in a markdown image tag (which is what generates the image you see above BTW):

![](https://ipfs.io/ipfs/QmV4JU8mw3TR7kDtwkkevXm6KyQFAbSJWZKoto8NXe8iGR)

We could check for this exact string, and put it in every repo. But it's a lot of work to change it if the file/hash changes, so maybe it should be:

[IPNS address of readme graphics]/contribute.gif

Then we could furthermore (optionally) add the other badges to the same IPNS place, and serve them all from IPNS, instead of some external service.

[dignifiedquire]

I suggest adding https://ci.appveyor.com/ to make everyone at least try to ensure things are working on windows as well :)

[jbenet]

+1 to appveyor.

@harlantwood though it's much better, im not ready to rely on IPNS yet. I think we can do with the hash for now.

[jbenet]

we could put it in a dir, so we have a .../filename.gif too

[RichardLitt]

Would https://github.com/ipfs/community/blob/master/contributing.md be good to link to, from the Contribute banner? I'm not sure, but I can't think of a better existing document.

[jbenet]

Yeah https://github.com/ipfs/community/blob/master/contributing.md works for me. Let's

• put the banner at the top of that doc too.
• put a link to the root repo and Project Directory:
  • https://github.com/ipfs/ipfs#ipfs---the-permanent-web
  • https://github.com/ipfs/ipfs#project-directory

[RichardLitt]

Can you PR the new ipfs/examples README to show me what you mean? I can then go about and add these to the other ones. https://github.com/ipfs/examples

[jbenet]

i mean put the banner + link to the root repo and project directory in the https://github.com/ipfs/community/blob/master/contributing.md doc

[RichardLitt]

@harlantwood What do you think about setting up a GitHub bot to PR repos that don't conform? I think that project-repos covers a lot of things mentioned here. We should still have a guide, though.

[harlantwood]

@RichardLitt I think it's an awesome idea! I don't have the bandwidth to take this on myself, but would be happy to offer suggestions etc... perhaps it would want to share some code with what is now in https://github.com/ipfs/project-repos/ -- if so we could extract that common code into an npm module...

[harlantwood]

Probably there are dedicaed github bot frameworks already, but if we were rolling our own with webhooks, I recommend https://www.npmjs.com/package/githubhook

[RichardLitt]

@harlantwood Cool. I've started over at ipfs-readme-standard. Having fun with remark/redast. We might be able to share some of the code, I've been modularizing as much as possible.

[hackergrrl]

There are a lot of good ideas about important common README components over in this standard issue and in standard-readme.

Authors should also strongly consider an API section: usage examples aren't enough to fully explain a module's API.

[RichardLitt]

@noffle I've been following those threads for a while. The project seems to have stalled, so I'm going to see if I can develop something similar to what was intended.

[RichardLitt]

Also:

• Deactivate the wiki.

Should be a requirement.

[daviddias]

What's missing for this endeavour?