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

[Mr0grog]

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:

• Discussion (repos focused on discussion in the issues or documenting/discussing notes and ongoing work, e.g. ipfs/research or ipfs/pm)
• Docs (repos focused on documentation, specs, etc.)
• Resource (Images, style guides, other common files/resources that aren’t software source code)

And I might mark the repos them this way:

• Description always starts with “<CATEGORY>:” e.g. “DISCUSSION: Repo to organize our ideas about research implementations of CRDTs.”
• Readme title always starts with “<Category>:” e.g. “Discussion: CRDT Research”
• Make sure the readme clearly describes how the repo should be used (e.g. content is in the issues, what kind of discussions belong here vs. discuss.ipfs.io)

---

UPDATE: Current Resolution

Repo categories:

• Documentation (📚)
• Discussion (💬)
• Infrastructure (🚚)
• Website (🤖)
• Resource (🎨)

Labeling:

• Add the topic type-<category> (e.g. type-discussion) (EDIT: was previously type:<category>)
• Prefix the README title with the category, e.g. Discussion: CRDT Research
• Prefix the repo description with the emoji associated with the category, e.g. “💬 Repo to organize our ideas about research implementations of CRDTs”
• Ensure the text immediately following the README title describes how the repo is used (e.g. it’s not a software project; it’s a place for discussion [in the issues] and to store links/papers/primers on related subject matter).

Repos That Need Fixing

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

Documentation:

• https://github.com/ipfs/ipfs
• https://github.com/ipfs/specs
• https://github.com/ipfs/papers
• https://github.com/ipfs/awesome-ipfs issue: Update repo description and topics to new non-code repo standards ipfs/awesome-ipfs#158
• https://github.com/ipfs/glossary
• https://github.com/ipfs/reading-list
• https://github.com/ipfs/pdd

Website:

• https://github.com/ipfs/website
• https://github.com/ipfs/blog
• https://github.com/ipfs/distributions
• https://github.com/ipfs/archives
• https://github.com/ipfs/docs
• https://github.com/ipfs/cid-utils-website

Discussion:

• https://github.com/ipfs/community
• https://github.com/ipfs/pm
• https://github.com/ipfs/notes
• https://github.com/ipfs/research-blockchain-data
• https://github.com/ipfs/archive-format
• https://github.com/ipfs/bitswap-ml
• https://github.com/ipfs/apps
• https://github.com/ipfs/ops-requests (Or maybe this is infrastructure?)
• https://github.com/ipfs/2016-Q3-Workshop
• https://github.com/ipfs/in-web-browsers
• https://github.com/ipfs/test-lab
• https://github.com/ipfs/research-bitswap
• https://github.com/ipfs/research-CRDT
• https://github.com/ipfs/research-p2p-video
• https://github.com/ipfs/research
• https://github.com/ipfs/dynamic-data-and-capabilities

Infrastructure:

• https://github.com/ipfs/infrastructure
• https://github.com/ipfs/pinbot-irc
• https://github.com/ipfs/sprint-helper
• https://github.com/ipfs/jenkins-libs
• https://github.com/ipfs/websiter
• https://github.com/ipfs/jenkins
• ✘ https://github.com/ipfs/dweblink-infra (Deprecated)
• https://github.com/ipfs/ci-helpers
• https://github.com/ipfs/ci-sync

Resource:

• https://github.com/ipfs/logo
• https://github.com/ipfs/artwork

[alanshaw]

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]

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]

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]

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:

• Documentation (📚)
• Discussion (💬)
• Infrastructure (🚚)
• Website (🤖)
• Resource (🎨)

Labeling:

• Add the topic type-<category> (e.g. type-discussion) (EDIT: was previously type:<category>)
• Prefix the README title with the category, e.g. Discussion: CRDT Research
• Prefix the repo description with the emoji associated with the category, e.g. “💬 Repo to organize our ideas about research implementations of CRDTs”
• Ensure the text immediately following the README title describes how the repo is used (e.g. it’s not a software project; it’s a place for discussion [in the issues] and to store links/papers/primers on related subject matter).

[Mr0grog]

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]

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]

@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]

@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]

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

[Mr0grog]

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:

• Pick any repo from the list at the top of the issue that doesn’t already have link to an issue and submit an issue or PR as appropriate:
  • PR to update the README title to explain how the repo is used
  • Issue to request a repo admin update the description and topics
  • Post back here with the issue/PR number so we can put it in the checklist to monitor it.
• If you are an admin on one of the listed repos, just go ahead and make those changes!

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]

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

• Home of the code that generates docs.ipfs.io
• Project management overall for the docs team
• Documentation (natch)
• Discussion on future docs efforts

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