Dos and don’ts when sunsetting open source projects

Maintaining an open source project can be a big responsibility. But it’s not one you’re obligated to bear forever. Maybe usage has declined thanks to a better solution. Maybe technology has evolved to the point that it’s easier to start over with a new project than adapt an old project to a new ecosystem. Sometimes it’s time to move on, even if that means deprecating a project.

Brett Terpstra, a front-end developer, maintains more than 100 GitHub repositories and has had to retire more than a few. “Projects that rely on APIs and other outside applications often require more work than is worthwhile once things start to break,” he explained in a Q&A. “Historically, those are the projects that get retired the fastest.”

Whatever your reasons, you want to sunset the project gracefully to protect your reputation and do right by your users. Here are some insights from maintainers who have navigated the process about what you should and shouldn’t do when it’s time to deprecate a project.

Don’t: Keep maintaining something for too long

The one thing Olga Botvinnik, a computational biologist, would tell her younger self is that she should have sunsetted her Python data visualization package prettyplotlib sooner. She didn’t want to abandon the project, but she had started it as part of her PhD work, felt like updating it to support Python 3 would be daunting, and was interested in moving on to other projects. Besides, another Python visualization library called Seaborn was becoming increasingly popular. 

“Even if I’m immediately done working on a project, I leave the 30-day window open to take care of issues and help users transition.” – Brett Terpestra, front-end developer

Botvinnik thought Seaborn was better in some ways, and more polished. So she made the decision to deprecate prettyplotlib and spend her time contributing to Seaborn instead. “One of my mentors told me that knowing when to end a project is just as good as finishing it,” she says. “That made me feel a lot better about letting it go.”

Do: Leave the door open for someone else

That said, you shouldn’t deprecate a project without considering other options, like handing it to another maintainer. Terpstra has deprecated many projects, but he always looks for someone else to take them over first. “There are different degrees of sunsetting,” he says. In some cases, a project is so simple that it doesn’t need much maintenance. In that case, you can just make a note that you don’t often update the project while leaving the door open for new contributions.

Of course it’s not always appropriate to hand off a project to another maintainer. Ben Johnson, maintainer of the SQLite recovery tool Litestream, opted to retire BoltDB and point people towards a fork called BBolt rather than have someone take over the original. “My name and reputation were pretty closely tied to the project at the time,” says Johnson. “I was the BoltDB guy. I didn’t want to put my reputation in the hands of someone else.”

Don’t: Pull the plug without notice

Terpstra gives at least a month’s notice before retiring a project. “Even if I’m immediately done working on a project, I leave the 30-day window open to take care of issues and help users transition,” he says.

“One of my mentors told me that knowing when to end a project is just as good as finishing it. That made me feel a lot better about letting it go.” – Olga Botvinnik, computational biologist

Once you’ve made the decision to deprecate a project, you need to let users know and, if possible, suggest alternatives. “I spread word through a blog post and a tweet announcing that I wasn’t going to actively fix bugs anymore and pointed people to Seaborn instead,” Botvinnik says.

Do: Keep the code online

Instead of deleting your project, it’s almost always best to archive it instead. Archiving a project makes it read-only and communicates to users that it’s no longer maintained. Everything from issues and pull requests to milestones and permissions become read-only. But you can always unarchive a project if you later decide to work on it again.

Deleting your project could have unintended consequences. “Anyone thinking about taking their software offline should consider whether they might be creating reproducibility problems for people in science and academia,” Botvinnik points out.

Keeping it online means that even if you couldn’t find someone to take it over before you deprecated the project, someone else could come along later and fork it—or at least find something useful to reuse.

That said, if you believe your code is actively harmful, it might be best to take it offline. For example, software with dangerous security vulnerabilities that put users at risk.

Take this with you

Ultimately, open source projects are living entities—born from passion and sustained by community. Knowing when and how to let go is not just good stewardship, it’s an essential part of the open source lifecycle.