Skip to content
This repository was archived by the owner on Jun 2, 2020. It is now read-only.
This repository was archived by the owner on Jun 2, 2020. It is now read-only.

GitHub Hygiene: Develop a standard way to indicate a repo/project is deprecated #54

Closed
Closed
GitHub Hygiene: Develop a standard way to indicate a repo/project is deprecated#54
Labels
dif/easySomeone with a little familiarity can pick upeffort/weeksEstimated to take multiple weekshelp wantedSeeking public contribution on this issuetopic/design-contentContent design, writing, information architecturetopic/docsDocumentation
@Mr0grog

Description

@Mr0grog
Mr0grog
opened on Mar 16, 2018

Developers who are building things on top of IPFS have pretty much all indicated that they’ve solved a lot of their problems by digging through IPFS source code and through the repos here on GitHub. Unfortunately, a huge proportion of repos there are deprecated, but not clearly marked as such (gray, red, and possibly many of the orange lines in that spreadsheet), making that job much harder.

We won’t suddenly have perfect docs that solve all of their problems tomorrow, so we should coming up with a standard way of marking out deprecated repos that we can easily and quickly apply:

  • Have a standard indicator/text in the repo description
  • Have a standard indicator/text at the start of the readme
  • Think about a policy for when/how to archive repos (makes them read-only and hides them from most listings)
  • Apply it to all repos that should be deprecated.
  • Also think about the same things for repos that are “in hibernation.” (And should any of those be deprecated instead?)

I’d suggest:

  • Description always starts with “DEPRECATED:”
  • Readme title always starts with “DEPRECATED:”
  • Immediately below the readme title there should be a bold or italicized paragraph about:
    • Why it was deprecated
    • When it was deprecated
    • Where to go for the same resource/functionality/whatever now (if applicable)

(Edit: surfacing our final decisions here so they are easy to find)

Conclusions/Final Process

  • Add the topic deprecated to the repo (pulling this over from GitHub Hygiene: Develop a standard way to indicate non-code repos #57)
  • Prefix the repo’s description with “DEPRECATED:”
  • Prefix the README title with “DEPRECATED:” (If a repo does not have a readme or its readme is empty, add one with the title: “DEPRECATED: [repo name]”
  • Follow the README title with a paragraph describing:
    • Why it was deprecated
    • When it was deprecated
    • Where to go for the same resource/functionality/whatever now (if applicable)
  • Finally, if a repo is dead, archive it (but don’t delete it). A dead repo might be ipfs.js, while a non-dead, non-archived one might be newsletter, where we might bring it back in the future.
    • Why archive? links still work, but this hides it from most views and lists on GitHub, drastically reducing noise and confusion. For repos like support, this also prevents people from posting new issues.
    • Downsides: issues and discussions get frozen. We may want to preserve that functionality on some repos (e.g. ones that are freshly deprecated or that haven’t gained any traction/that we can’t support, but that we might want to revisit later).

Checklist of Repos to Fix

Definitely deprecated repos:

Things that might be dead, but need clarity from their owners/maintainers:

Already archived, but missing standard notices: (How much do we care to update?)

Turned out not to be dead:

Metadata

Metadata

Assignees

No one assigned

    Labels

    dif/easySomeone with a little familiarity can pick upeffort/weeksEstimated to take multiple weekshelp wantedSeeking public contribution on this issuetopic/design-contentContent design, writing, information architecturetopic/docsDocumentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions