search

ipfs-inactive / docs

[ARCHIVED] 🤖 📚 IPFS documentation working group, plus IPFS docs site code
https://docs.ipfs.io/
Other
87 stars 62 forks source link

GitHub Hygiene: Develop a standard way to indicate non-code repos #57

Closed Mr0grog closed 4 years ago

Mr0grog commented 6 years ago

Similar to #54, we need clear indicators of repos that aren’t software. See the “key” tab the repo inventory for some categorizations: https://docs.google.com/spreadsheets/d/1IDVAGfniyHCJLIxLc3y7K7YTOFGCtgwTVCZEojtNLlw/edit#gid=1355406849

I think I might categorize them this way:

And I might mark the repos them this way:

UPDATE: Current Resolution

Repo categories:

Labeling:

Repos That Need Fixing

The following is based on https://docs.google.com/spreadsheets/d/1IDVAGfniyHCJLIxLc3y7K7YTOFGCtgwTVCZEojtNLlw

Documentation:

Website:

Discussion:

Infrastructure:

Resource:

alanshaw commented 6 years ago

We often put an emoji as the first character of the description.

📚 is docs 💾 is infrastructure (ansible/chef/puppet scripts etc.) 🤖 for repos built by our automated static site generator etc.

victorb commented 6 years ago

Emojis are fine for us who will get used to it, but new folks won't have any idea what it means until they see some index describing what they mean, and they will easily be forgotten. Could be nice to have together with what @Mr0grog is suggesting though.

Another thing we can do is to use the repository tags as metadata. Adding type:discussion for repositories that are for discussions and so on. Would also help with automation as our scripts can then use those tags for querying for only type:code repositories and so on.

Edit: sorry, they are not called tags in Github language, I'm thinking about the topics.

Mr0grog commented 6 years ago

Emojis are fine for us who will get used to it, but new folks won't have any idea what it means until they see some index describing what they mean, and they will easily be forgotten.

This is also one of the reasons icons consistently perform poorly against text for buttons in usability studies :)

That said, I think icons/emoji might be OK in the description as long as they are paired with text in the readme. Not sure on 💾 for infra. What about 🚚 or 🔌?

Use the repository tags as metadata. Adding type:discussion for repositories that are for discussions and so on. Would also help with automation as our scripts can then use those tags for querying for only type:code repositories and so on.

👍 on that.

Mr0grog commented 6 years ago

OK, I think we need to move forward with this. I’ll bring this up for last call feedback in next week’s all hands (2018-04-30). In the mean time, I think what we’ve got at this point is:

Repo categories:

Labeling:

Mr0grog commented 6 years ago

Ok, there’s been no feedback, so let’s go with the above.

@VictorBjelkholm or anybody else who has access rights, interested in helping update all the relevant repos?

EDIT: moved repo checklist from here to the top of the issue.

Mr0grog commented 6 years ago

Add the topic type:<category> (e.g. type:discussion)

I just tried to add these to this repo and discovered GitHub does not allow colons in topics (just letters, numbers, and hyphens). How about type-<category> (or type--<category> if we need more differentiation)?

/cc @VictorBjelkholm, I think you were the most interested in setting topics.

vmx commented 6 years ago

@Mr0grog is "type" needed? The labels are under our control so we just need to make sure they are distinct. If there's a label discussion it would then be clear that it is a that type. Or could there be labels that belong to multiple types?

victorb commented 6 years ago

@vmx reason for prepending anything is so we can have automated tools that are making decisions based on those. As there won't be any distinction without a prefix, the tool won't realize it doesn't have to care about something being labelled as ipfs vs discussion.

@Mr0grog Using a - instead of : would be fine and seemingly the only option as well.

Mr0grog commented 6 years ago

👍 updated the post here that has the canonical info. Also added it all to the OP.

Mr0grog commented 6 years ago

Update here: we have a way we want to mark things and a list of repos that probably need those markings (see top of this thread). What this needs is:

Anybody who’s got some free time, just pick one repo from the list that’s not checked off and do the above! It would be enormously helpful.

jessicaschilling commented 4 years ago

In the time since this issue was opened, we're seeing repos being used as hybrids -- for example, even this docs repo, since it's used as

The issue has been dormant for so long that best practice now seems to be to close it, and re-open if necessary.