Feature deprecation process

Principles for successful deprecation

Below are a number of principles which have led to success in past deprecating projects:

• Craft an honest message: When conveying the reasoning to customers, it is important that you are as honest as possible about the reasoning behind sunsetting.
• Ensure you’re speaking to the customer: Often times when creating the external-messaging for deprecating a feature, it can be easy to focus on internal-jargon or story. Make sure any message you share is speaking in customer language which they will clearly understand. While customers may not always be happy that we’re shutting down a feature, we want them to understand why.
• Ensure each task has a single DRI and that each DRI understands their role: During deprecating process, it is common for the message about what is happening and when it is happening to get lost. Thus, it is critical to ensure each task has a DRI and that person clearly understands the timeline and expectations of their role.
• Prefer gradual deprecations: We should strive to gradually remove functionality over multiple releases to provide time for our customers and internal teams to make plans and adjust. For example, in a first release we use a feature flag to disable functionality by default and, in a subsequent release we remove the functionality entirely. How we achieve this gradual deprecation should be assessed on a case by case basis depending on the usage, importance of the feature, impacts of removing and other factors.

Choosing to deprecate a feature

You should first determine the potential impact of the feature deprecation:

• Are any users using the feature? Who are they? Is there another feature that also meets their needs?
• Are any Sourcegraph teams using the feature, or a subset of its code?
• Are any sales prospects specifically interested in the feature?

Be sure to talk to the the parties above and ensure you really understand the impact of the deprecation. If the answers to these questions confirm that deprecation is the best path forward, you should next document the deprecation.

The process of deprecating a feature

Once the decision to deprecate a product or feature has been made, below is a recommend set of actions to ensure

1. Determine if you need an exception process. Some features may require extended migration periods to allow customers extended time to fully adopt a new solution.
2. Craft the message & build the internal enablement document. This document should include frequently asked questions, timelines, impacted customers, DRIs, and any other relevant information.
3. Share the message internally. You will know what channel is best but generally it is recommended to share in #eng-announce at a minimum. Please lean towards over-sharing in these cases to ensure everyone has a chance to see the message.
4. Identify a technical DRI to document the technical steps required. Ideally, this is the person who writes the plan, will be the one executing on the plan the day of the deprecating.
5. Segment out your customers. In many cases, shutting down a feature will impact certain users differently and each cohort of users may require slightly different messaging or CTAs. This is important to ensure each user feels comfortable with next steps.
6. Share with customers at minimum 30-days in advance. It is recommended to start with a broad email to those impacted and a publicly-facing blog post to outline the full story (examples below). It is important to think critically about who this email comes from (PM, CE, AE, etc) to ensure the message resonates most with the recipient.
7. Remind customers twice. 7 days and 1 day before. This is good practice to ensure that customers hear the message and are following any migration steps required.
8. Execute the deprecation.
9. Post-mortem. Following the wind down, make sure to update this page with learnings to improve this process in the future.

Documenting a feature’s deprecation

You should then create a blog post to publish when we deprecate the feature. The blog post should contain:

• Why we’re deprecating the feature.
• The deprecation timeline.
• Workarounds for the feature’s users, if relevant.

We document this in a blog post because blog posts are publicly accessible, timestamped, and easy to send directly to customers or prospects.

Other Considerations

Are you working closely alongside your PMM? They will help craft the message in a way that builds up Sourcegraph.

Are there legal impacts of the decision? Ask in #legal.

Will deprecating your feature impact other Sourcegraph features? Ask in #product.

Does deprecating your feature require a release? If yes, build your timelines around the release schedule.

Example Content