From 38e54ade93affdfe0e79e05da39b50bbd0c37dd5 Mon Sep 17 00:00:00 2001 From: Benjamin Granados Date: Mon, 30 Oct 2023 15:03:22 +0100 Subject: [PATCH 1/7] Initial version of deprecation process Initial version of deprecation process --- docs/deprecation-plan.md | 49 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/deprecation-plan.md diff --git a/docs/deprecation-plan.md b/docs/deprecation-plan.md new file mode 100644 index 00000000..5afe5976 --- /dev/null +++ b/docs/deprecation-plan.md @@ -0,0 +1,49 @@ +# The process of deprecating a feature + +Once the decision to deprecate a feature has been made through an ADR , below is a recommend set of actions: + +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, and any other relevant information. + +3. **Share the message internally**. The best Slack channel for this announcement is #announcements. The announcement should communicate the timeline and the related ADR. + +4. **Share with users at minimum 30-days in advance**. It is recommended to start with a broad social media announcement including a blog post. The blog post should contain: + - Why we’re deprecating the feature. + - What is changing. + - What do you need to do?. + - When is this change comming into effect? The deprecation timeline. + + +5. **Remind users twice**. 7 days and 1 day before. This is good practice to ensure that users hear the message and are following any migration steps required. The announcement will be shared in social media and Slack #announcements. + +6. **Execute the deprecation**. + +## Example Content + +### Deprecation Blog +Below are some examples of deprecation blog-posts: + - https://learn.microsoft.com/en-us/power-platform/important-changes-coming + +### Announcement Message + + 🚨 JSON Schema Announcement 🚨 + + We will be deprecating XXXXXXXXXX on 1 April 2021 to XXXXXXXXXX. + + Read more about the change here 👉 http-blog + Have questions? Join us on slack! + + +Below are some examples of deprecation announcements: + - https://twitter.com/SetProtocol/status/1652034604855967746 + - https://x.com/ShopwareDevs/status/1267813259689639938?s=20 + + +### 7- and 1-day Reminder Message + + Hi JSON Schema Community! + This is a reminder that XXXX will be deprecated in 1 week, on Monday, August 1. You can read more about the change on our blog 👉 http-blog + + Have questions? Join us on slack! + From 96bbc43d7550bbe9962bc05753fad6c6a0c7a7cf Mon Sep 17 00:00:00 2001 From: Benjamin Granados Date: Tue, 31 Oct 2023 10:53:29 +0100 Subject: [PATCH 2/7] More details in timelines and examples. --- docs/deprecation-plan.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/deprecation-plan.md b/docs/deprecation-plan.md index 5afe5976..eff5b58b 100644 --- a/docs/deprecation-plan.md +++ b/docs/deprecation-plan.md @@ -4,16 +4,18 @@ Once the decision to deprecate a feature has been made through an ADR , below is 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, and any other relevant information. +2. **Craft the message & build the internal enablement document**. This document should include frequently asked questions, timelines, and any other relevant information. The best approach here is to publish a blog post. -3. **Share the message internally**. The best Slack channel for this announcement is #announcements. The announcement should communicate the timeline and the related ADR. - -4. **Share with users at minimum 30-days in advance**. It is recommended to start with a broad social media announcement including a blog post. The blog post should contain: +3. **Share the message internally**. The best Slack channel for this announcement is #announcements. We will link a github announcement containing: - Why we’re deprecating the feature. - What is changing. - What do you need to do?. - When is this change comming into effect? The deprecation timeline. +The announcement should communicate the timeline and the related ADR. This will be shared before sharing it publicly with users (This can be done in the same day). + +4. **Share with users at minimum 30-days in advance**. It is recommended to start with a broad social media announcement including a reference to a blog post with the same content than the Github announcement. + 5. **Remind users twice**. 7 days and 1 day before. This is good practice to ensure that users hear the message and are following any migration steps required. The announcement will be shared in social media and Slack #announcements. From 1fcdee066cf4e9e84d0ea08cdbd500917fa9ce8d Mon Sep 17 00:00:00 2001 From: Benjamin Granados <40007659+benjagm@users.noreply.github.com> Date: Tue, 7 Nov 2023 14:55:01 +0100 Subject: [PATCH 3/7] Update docs/deprecation-plan.md Co-authored-by: Jason Desrosiers --- docs/deprecation-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deprecation-plan.md b/docs/deprecation-plan.md index eff5b58b..bfca0ce8 100644 --- a/docs/deprecation-plan.md +++ b/docs/deprecation-plan.md @@ -1,6 +1,6 @@ # The process of deprecating a feature -Once the decision to deprecate a feature has been made through an ADR , below is a recommend set of actions: +Once the decision to deprecate a feature has been made through an ADR, below is a recommend set of actions: 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. From 9742472996a1bcd884d6c99fcd313931d3a113bb Mon Sep 17 00:00:00 2001 From: Benjamin Granados <40007659+benjagm@users.noreply.github.com> Date: Tue, 7 Nov 2023 14:55:27 +0100 Subject: [PATCH 4/7] Update docs/deprecation-plan.md Co-authored-by: Jason Desrosiers --- docs/deprecation-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deprecation-plan.md b/docs/deprecation-plan.md index bfca0ce8..97ca4efc 100644 --- a/docs/deprecation-plan.md +++ b/docs/deprecation-plan.md @@ -4,7 +4,7 @@ Once the decision to deprecate a feature has been made through an ADR, below is 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, and any other relevant information. The best approach here is to publish a blog post. +2. **Craft the message and build the internal enablement document**. This document should include frequently asked questions, timelines, and any other relevant information. The best approach here is to publish a blog post. 3. **Share the message internally**. The best Slack channel for this announcement is #announcements. We will link a github announcement containing: - Why we’re deprecating the feature. From ecaf11bc3b5e78cb7563bf24f8e00f47ad555216 Mon Sep 17 00:00:00 2001 From: Benjamin Granados Date: Tue, 7 Nov 2023 15:19:06 +0100 Subject: [PATCH 5/7] Add clarification of the Scope and recommendation for non-breaking changes. --- docs/deprecation-plan.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/deprecation-plan.md b/docs/deprecation-plan.md index 97ca4efc..59fe7a5d 100644 --- a/docs/deprecation-plan.md +++ b/docs/deprecation-plan.md @@ -1,3 +1,7 @@ +# Scope of this document + +This document is intenteded to describe the process to deprecate features other than changes in the Specification. Changes in the Specification are handled by the Specification development process. + # The process of deprecating a feature Once the decision to deprecate a feature has been made through an ADR, below is a recommend set of actions: @@ -49,3 +53,19 @@ Below are some examples of deprecation announcements: Have questions? Join us on slack! +# Recommendations to communicate other non-breaking changes + +The process described before will cover breaking changes, however we can use some of the practices described to better handle other non-breaking changes. For those cases this is the recommended process: + +1. **Share the message internally**. The best Slack channel for this announcement is #announcements. We will link a github announcement containing: + - What is changing. + - What do you need to do?. + - When is this change comming into effect? The deprecation timeline. + +The announcement should communicate the timeline. + +2. **Share with users at minimum 30-days in advance**. We'll use again Slack #announcements and a GitHub announcement. + +3. **Remind users twice**. 7 days and 1 day before. This is good practice to ensure that users hear the message. We'll use again Slack #announcements and a GitHub announcement. + +4. **Execute the change**. \ No newline at end of file From f142761ef342174c7f9030bf7480cb7d6a061e1e Mon Sep 17 00:00:00 2001 From: Benjamin Granados Date: Wed, 15 Nov 2023 15:31:59 +0100 Subject: [PATCH 6/7] Changes requested in 13-11-23 Community Meeting Refer to the plan as breaking changes plan instead of deprecation plan. --- docs/deprecation-plan.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/deprecation-plan.md b/docs/deprecation-plan.md index 59fe7a5d..ff0c9587 100644 --- a/docs/deprecation-plan.md +++ b/docs/deprecation-plan.md @@ -1,10 +1,10 @@ # Scope of this document -This document is intenteded to describe the process to deprecate features other than changes in the Specification. Changes in the Specification are handled by the Specification development process. +This document is intenteded to describe the process to follow in case of breaking changes other than changes in the Specification. Changes in the Specification are handled by the Specification development process. -# The process of deprecating a feature +# The process for breaking changes -Once the decision to deprecate a feature has been made through an ADR, below is a recommend set of actions: +Once the decision to proceed with the breaking change has been made through an ADR, below is a recommend set of actions: 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. @@ -53,9 +53,9 @@ Below are some examples of deprecation announcements: Have questions? Join us on slack! -# Recommendations to communicate other non-breaking changes +# Recommendations to communicate other critical changes -The process described before will cover breaking changes, however we can use some of the practices described to better handle other non-breaking changes. For those cases this is the recommended process: +The process described before will cover breaking changes, however we can use some of the practices described before to better handle other critical changes. For those cases this is the recommended process: 1. **Share the message internally**. The best Slack channel for this announcement is #announcements. We will link a github announcement containing: - What is changing. From c29733ed9f17158d11fe3034829595d57b709638 Mon Sep 17 00:00:00 2001 From: Benjamin Granados <40007659+benjagm@users.noreply.github.com> Date: Thu, 16 Nov 2023 11:12:06 +0100 Subject: [PATCH 7/7] Update docs/deprecation-plan.md Co-authored-by: Jason Desrosiers --- docs/deprecation-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deprecation-plan.md b/docs/deprecation-plan.md index ff0c9587..f182eddd 100644 --- a/docs/deprecation-plan.md +++ b/docs/deprecation-plan.md @@ -23,7 +23,7 @@ The announcement should communicate the timeline and the related ADR. This will 5. **Remind users twice**. 7 days and 1 day before. This is good practice to ensure that users hear the message and are following any migration steps required. The announcement will be shared in social media and Slack #announcements. -6. **Execute the deprecation**. +6. **Execute the change**. ## Example Content