When and How to Deprecate an Open Source Project

“If I have a thousand ideas and only one turns out to be good, I am satisfied,” is a well-known quote by Alfred Nobel, the Swedish chemist who held 355 patents in his lifetime and bequeathed his fortune to establish the Nobel Prize. I am often reminded of Nobel’s quote when “sunsetting” an open source project – one that may once have been healthy, representative of a developer’s idea or experiment, or a user’s opportunity to learn hands-on about open source.

Failure is a necessary part of the innovation process

My work on sunsetting inactive open source projects started when I wanted to find ways to prevent failures and improve project health. GitHub data shows that 16% of more than 8,000 open source projects by major tech companies have become inactive within 12 months’ time. That’s 1,280 projects! But I soon learned that the abandoning of projects can’t always be prevented. “Open” innovation dictates following the next best idea and that means some projects must become obsolete and get left behind.

I changed my focus to developing a sunsetting program, which I called “Git in Order.” The program entailed maintaining an up-to-date record of open source repositories, monitoring the activity status of projects and, as a good open source citizen, addressing security, transparency and reputation concerns. Git in Order also included cleaning up inactive projects, of course, a process I’ve honed into a straightforward six-step approach.

6-step approach to responsibly deprecating a project

This process has worked extremely well for VMware’s Open Source Program Office. The first three steps are better suited for larger portfolios of projects, such as a set of company-originated repositories, and is ideally carried out by an OSPO. (If you are considering whether to deprecate one or a few projects and how you’d go about doing it, you may still find some of this information useful or you can jump to step 3.)

1. Update/create a list of projects and determine the inactive ones

Begin by investigating the contacts and owners of repos and creating a list of projects on GitHub (and other places like Bitbucket, GitLab, Google Code or SourceForge). If you’re working with a large list, filter them by the “Last Commit Date” or the “PushedAt” date, which helps shorten the list of potentially abandoned projects. If a repository has no commits for the last 12 months, it is likely inactive. Looking at the last PRs or the responses on the issues could also help determine whether a repository is still being maintained. The existence of unresolved security issues (Dependabot or other alerts) is another criterion for deeming a project inactive.

Note: If such a review has never been done or is done in longer intervals, it might be challenging to find the proper contacts. Having access to the repository would certainly help find users with more privileges. When I initially started the regular reviews, I had cases where much more investigation was needed, including looking at release notes, blog posts and other internal or external information to find the proper owner of a repo.

2. Decide where to host inactive projects

Active and inactive repositories are best kept separate. An important part of our initial Git in Order goal was to improve the monitoring of the open source repositories, and we soon concluded that inactive repositories shouldn’t be mixed with the active ones. We decided to create a separate GitHub organization to host all deprecated projects. Moving repositories doesn’t break any existing links (GitHub redirects them), but teams and member access are lost (intentional in our case). This effort could potentially not only reduce costs by cleaning up inactive repos and members, but help to better monitor the active repositories in creating a shorter list of projects to check for activity, timely responses, compliance, security, etc.

3. Decide whether to sunset inactive projects

a. Get approval

Talking people into deprecating the results of their work might be difficult. Make sure you’re clear on the goals, e.g., reducing costs, reducing reputation risk and minimizing security concerns. In many cases, this is just a confirmation by the maintainers and the community, but depending on the project size, this could also be a process involving your leadership, product management, OSPO and marketing colleagues to approve the deprecation.

b. Check the dependencies

Evaluate the project by looking closely at contributions, users, forks and which other projects depend on it to determine if it’s a candidate for sunsetting (not every project can / should be sunset). If possible, contact the Open Source Program Office, other colleagues or community members to discuss suitability. The Linux Foundation’s Open Source Security Foundation (OSSF) has developed a criticality score that can help you with this evaluation.

Also, validate that the project isn’t referenced anywhere else in your other projects that are still actively maintained. Update any location where artifacts are published (i.e., community content repositories like npm, PyPI, RubyGems, etc.) to clearly state that “this repository will no longer be updated.”

4. Communicate the decision to deprecate the project

Be transparent with the reasons for deprecating a project and the benefits reaped from a shorter backlog. Update the file to clearly state at the top the project has been deprecated and the repository will no longer be updated. If applicable, in the, suggest alternate projects that provide similar functionality.

Depending on the project and how the community communicates, it may or may not make sense to issue a statement to the mailing list or other communication channels, such as Slack. Don’t forget to also update all web pages, wikis and any other online project documentation.

If your project has been involved in marketing and branding, reach out to your contacts and inform them of the project’s decision to sunset. 

5. Archive the project

GitHub provides the option to archive a repository, which will restrict access to read-only. After archiving the repo, you can move it into another organization or separate it in some way from the active repositories. In this way only a few people with owner privileges would be able to un-archive and revive the project, if that’s needed.

6. Be prepared to un-archive the project

Why follow all these steps if it’s possible that they’ll all need to be reversed? My experience as an OSPO member working with project owners has proven that allowing the possibility to un-archive a project later could be the tipping point for convincing an owner to agree with the archival! It is very rare that projects are reactivated; however, being prepared with a list of simple steps is beneficial should the request come in. Also, make sure to check compliance, security and points of contact and ask for the plans to better maintain and further develop the “new” project.

In closing

The most important step you can take when ending a project is to be transparent with users at every step of the way. Being open about your intentions establishes trust for future work with all potential developer and user communities.

See my talk on the subject at the Open Source Summit EU 2022 here and stay tuned for the second part of this blog series where I’ll discuss early indicators and common reasons for abandoning a project.

Stay tuned to the Open Source Blog and follow us on Twitter for more deep dives into the world of open source contributing.


Leave a Reply

Your email address will not be published. Required fields are marked *