deprecation-checklist.md

deprecation-checklist.md

How To Deprecate A Repository on GitHub

A simple checklist for deprecating a repository. See https://github.com/RichardLitt/knowledge/blob/master/how-to-deprecate-a-repository-on-github.md.

Deprecating a project no one uses

• Change the GitHub description. This is often the first thing people see for the repository, and the first line that people will see if looking at the repository in the Organization view. The most important thing to do is to add the word DEPRECATED at the front of the description. This clearly marks it will not be updated. You can also add an emoji to it. ⛔️ DEPRECATED <former description> makes it pop out a bit more.
• Add GitHub topics: deprecated, obselete, and archived are all good ones.
• Edit the title of the README. Remove the current title, and instead write # DEPRECATED.
• Add a reason to the README, at the top, stating that: “This is no longer supported, please consider using XXX instead.” If there is a reason for deprecating the repository, add it here. It should be unambiguous to anyone visiting the repository that it will not be maintained or updated again.
• Update any licenses or liability wavers. By updating them, you make sure that they are legally valid, going forward. This can stop questions popping up in the years to come, if people rediscover the project and want to use it. Note: I am not your lawyer. If you have questions, seek legal counsel.
• Add a no-maintenance-intended badge. This is another visible way of pointing out that you’re not going to keep updating this project, and the idea comes from unmaintained.tech.

Deprecating active projects

• Open an issue asking users to either (pick one):
  • Ask people to use a different project, which solves the same problem as yours (and hopefully has more features and better UX).
  • Ask people to fork the project and take over maintenance going forward.
  • Ask contributors to step up to become collaborators and maintainers. Offer them access to the repository, so that they can maintain it for you, while you offload your responsibilities.

If you are interested in the project continuing, but don’t need it to be tagged with your name anymore, you can do this:

• Move ownership of the repository to another maintainer. If, for instance, the project was at RichardLitt/awesome-project, you could give it to someone you trust who is maintaining it. Do this in the repository settings. For instance, I could ask my friend Gregor to take it over, and move it to gr2m/awesome-project.
• Set up an organization to take over the project. If the project is large, and there is an ecosystem around it, it is sometimes smart to set up an organization to take if over, so that it is clear that you are not in charge of it, but all the members of the organization. This is a similar option to moving it to another maintainer, but it stops you from needing to choose one sole maintainer to take it over.

If it is a JavaScript project on npm

• Use npm deprecate to deprecate it. Don’t forget to publish.
• Edit the description to include the badge, as on GitHub. ⛔️ DEPRECATED <former description> would be useful. Don’t forget to publish a patch with the new metadata.