Deprecation Process

Deprecating features or interfaces is a delicate process, and must be handled with care and empathy for end-user. This page lists the steps to take in order to manage a successful deprecation.

Problem formulation - Why and what?

It all starts with why. The accountable person clearly states why we need to make this change. This is indispensable for creating alignment with other stakeholders and for crafting the end-user communication. This will create an understanding of how much effort is needed by the end-users to adapt to the change, and how much supporting material needs to be produced.

RACI - Put together a team

The accountable person decides who should be responsible and do most of the ground work. These can be the same person if the work is done by a single individual, but in the case of a multiple-persons effort, one person needs to remain clearly accountable. The responsible person in turn will need support to perform the tasks, thus the consulted parties are identified, as well as who should be informed.

RACI	People
Responsible	Alice, Bob, Radek, Imane
Accountable	Alice
Consulted	Security Response Team, GHC Team
Informed	Release engineering, QA, H.org comms

Timeline

To this effect, we follow a timeline of 4 releases, during which we gradually roll out the deprecated feature.

flowchart TD
   A1(Decision to start deprecation)
   A2(Inform the community of the timeline)
   B1(Include deprecation notice in the changelog)
   B2(Show a warning when the command is used)
   B3(Remove code paths from the code base but keep interface)
   B4(Remove legacy interface)


   C1[Introduce alternative]
   C2[Alternative is recommended]
   C3[Alternative implements the old interface when applicable]
   C4[Alternative takes over]
   subgraph Preparation
   A1 --> A2
   end
   subgraph Release N
   A2 --> B1 
   A2 --> C1
   end
   subgraph Release N+1
   B1 --> B2
   C1 --> C2
   end
   subgraph Release N+2
   B2 --> B3
   C2 --> C3
   end
   subgraph Release N+3
   B3 --> B4
   C3 --> C4
   end

Loading