Deprecation Process

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

TL;DR

1. Define the problem at hand and create a wiki page for the process
2. Identify the team
3. Follow the timeline

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

Scope

It is important to understand the impact. An initial communication to the community should be made in order to have some limited understand of the potential impact. It is useful to contact people using cabal in both typical and extreme settings (Agda, GHC, industrial users). It is fundamental that the deprecation scope is well-understood by both the RACI team and the end-users.

Communication

Most of the groundwork is already done if the steps above have been followed. Since the reason for the change is defined, along with its effect on the end-users and what they need to do and when, this simply needs to be put together into one clear and empathic message.

Remember that we serve a majority of the Haskell population out there.

The responsible people collaborates with the informed parties to create a draft that is sent through our communication channels.

As we do not deprecate a feature from one release to the next, each release until the final one needs to have a changelog entry to remind the end-users of the currently active deprecation processes.

Timeline

To this effect, we follow a timeline of 4 releases, during which we gradually withdraw 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