draft post

Author: hanwg

.vscode/tasks.json

@@ -0,0 +1,17 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "preview",
+            "type": "shell",
+            "command": "./hugo.exe server --buildDrafts --buildFuture",
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}

content/posts/2026/01/deprecation-and-migration/index.md

@@ -17,15 +17,49 @@ I recently deprecated a beloved software feature.
 
 The feature had been in service long before I was involved in the project and was serving a user base of over 10k.
 It functioned as smoothly as the day it was released; it was stable, (mostly) bug-free and performant.
-Now, most people would think, *"If it ain't broke, don't fix it"*.
+Now, most people would think, _"If it ain't broke, don't fix it"_.
 
 Sadly, reality is different and things were more complicated.
 
 Under the hood, the feature was tightly coupled with legacy APIs and outdated dependencies.
-Maintaining or extending it with new functionalities was difficult if not impossible. 
+Maintaining or extending it with new functionalities was difficult if not impossible.
 Furthermore, the feature requires complex configuration which often confuses and frustrates new users.
 
 Ultimately, I felt that it was a blocker to progress.
-The feature had served the project well, but it was time for it to go and make way a more modern and intuitive solution.
+The feature had served the project well, but it was time for it to go and make way for a more modern and intuitive solution.
 
-## The Deprecation
+## The Deprecation Process
+
+### Change Freeze
+
+One of the early steps is to freeze changes on the feature to be deprecated.
+This is typically done by adding a `@deprecated` annotation to the feature.
+The deprecation signals the intent to remove the feature in a future release.
+This helps developers to avoid redundant Pull Request (PR) and also helps to direct development efforts to the new solution.
+
+### Implement the New Solution
+
+**Feature Parity.**
+**Backward Compatibility.**
+**Ease of Migration.**
+
+### Communication
+
+There are various aspects to consider when communicating the deprecation to users.
+
+**Communication channels.** To ensure that the message reaches all the intended audiences, communication of the deprecation was done via the following channels:
+
+- Log files: A warning is logged whenever the deprecated feature is used. Since log files are often monitored by system administrators, warning messages can be used to alert them.
+- Release notes: A <abbr title="Too Long; Didn't Read">TLDR</abbr> version of the deprecation message. Unfortunately most people don't read this or miss it especially when the release notes are long.
+- Project forums and social media: Besides functioning as a channel for deprecation announcements, it is also a good place for discussions and to get feedback.
+- Project repository and project management site: Intended for developers, the technical aspects of the deprecation are detailed here.
+- Project documentation site: The primary source of information for everyone.
+- Notifications: Send a notification when the deprecated feature is used.
+
+**Communicating the Deprecation.** For the deprecation message to be effective, I included the following elements:
+
+- Context: Provides a short summary or background about the feature.
+- Reason: Explains why the feature is being deprecated (for example, technical debt, compatibility with newer APIs, etc.).
+- Impact: Highlight the impact if the feature is not deprecated (for example, security vulnerabilities, performance issues, etc.).
+- Migration: Provide a migration plan to help users adopt the new solution. Provide examples and explain alternatives if available.
+- Time frame: Give a time frame to allow users to plan for the deprecation. Be as clear as possible such as providing the exact date or version where the feature will be removed.