ipfs/awesome-ipfs

Add build instructions to README

Mr0grog opened this issue · 13 comments

Mr0grog commented

Now that this repo is more a site than just a README, it would be a good idea to add build instructions (even if it’s just “run make build”).

While we’re at it, it might also help to clarify somewhere that the files to change when submitting a PR are in /data and that the README is generated from those. (That’s strongly implied in CONTRIBUTING.md, but that file never straight-up just says this. It’s also a doc someone could easily miss, especially if they are familiar with what awesome-ipfs was just a few days ago.)

koalalorenzo commented

I find this very confusing to be honest, as we are expecting a simple markdown structure.
Isn't there any way to simplify this? You can either have the README or the Website, but the PRs that are coming are almost always just one of the two...

Example:
#165
#157

daviddias commented

@koalalorenzo I believe that is because there are no instructions that you need to use -- https://github.com/ipfs/awesome-ipfs/blob/master/scripts/make-readme.js -- to generate the updated README.

koalalorenzo commented

I'll have a look at this tomorrow morning or this evening! Adding some guidelines will help a lot!

hacdias commented

By the way, to change the README you have to change the README template. Do not edit it directly.

Mr0grog commented

Making that clear is kinda the point of this issue 😜

koalalorenzo commented

@hacdias I was wondering as it was not clear enough... JK! It is clear enough to me but it has to be documented: not everybody got that... this seems something very common

hacdias commented

@koalalorenzo take a look at #177 to see if it's clear enough please 😄

koalalorenzo commented

LoL, I already made
#175

:D Don't you like my contribution? :D

hacdias commented

@koalalorenzo uh, yes. I'll close #177 and please add to #175 that if someone wants to change anything on the README that is not an element of the list, they need to change the README template instead. 😄

koalalorenzo commented

So, if we were agile this would be a user story: check the name of the branch that I am merging.

I made one by reading the issue: As a new contributor I want to know how I can build the repo so I can share and add value.

Rereading the issue but also having a look at all the contributions that are coming, would help to understand what is the problem to our end users.

I don't like the fact that @hacdias had to open a new PR to showcase this, you could have just modified it! :) I would like that instead. Now the point is on which PR is more clear, and I feel a little bit as an outsider. Please let me help you guys!!! 😞

  • ❤️1
hacdias commented

@koalalorenzo ahah. Like, what you changed on #177 was this:

In order to add an element to this list, you need to modify the files in /data and then run a simple make build before publishing your pull request as the Readme and the website are automatically generated.

That is correct. But there's still information missing.

You edited everything correctly. What I'm saying is that we still need to tell users how to change the README itself: edit the README template like you did. Could you add that?

  • 👍2
koalalorenzo commented

I am on it ❤️

  • 👍1