feat: Add deprecation warnings to Steps from Apps components and Docs (#1089)

WilliamBergamin · seratch · filmaj · web-flow · commit 28827082d443 · 2024-06-07T09:32:50.000-04:00
* Add warnings and comments

* deprecate in docs

* add deprecation warnings to examples

* Improve formating

* Update docs/_config.yml

* Update docs/_steps/workflow_steps_overview.md

Co-authored-by: Fil Maj &lt;maj.fil@gmail.com&gt;

---------

Co-authored-by: Kazuhiro Sera &lt;seratch@gmail.com&gt;
Co-authored-by: Fil Maj &lt;maj.fil@gmail.com&gt;
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -35,15 +35,15 @@ t:
     start: Getting started
     contribute: Contributing
     beta: BETA
-    legacy: LEGACY
+    deprecated: Deprecated
   ja-jp:
     basic: 基本的な概念
     steps: ワークフローステップ
     advanced: 応用コンセプト
     start: Bolt 入門ガイド
     contribute: 貢献
     beta: BETA
-    legacy: LEGACY
+    deprecated: 非推奨
 
 # Metadata
 repo_name: bolt-python
diff --git a/docs/_includes/sidebar.html b/docs/_includes/sidebar.html
@@ -56,8 +56,8 @@
   <ul class="sidebar-section">
     <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#steps">
       <li class="title">
-        {{ site.t[page.lang].steps }} 
-        <!-- UNCOMMENT AFTER GA <span class="label-legacy">{{ site.t[page.lang].legacy }}</span> -->
+        {{ site.t[page.lang].steps }}
+        <span class="label-deprecated">{{ site.t[page.lang].deprecated }}</span>
       </li>
     </a>
     {% assign workflow_steps = site.steps | sort: "order" | where: "lang", page.lang %}
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -49,8 +49,8 @@ <h3 id="{{section.slug}}">{{ section.title }}</h3>
         workflow_steps %}
         <div class="section-wrapper">
           <h3 id="{{section.slug}}">
-            {{ section.title }} 
-            <!-- UNCOMMENT AFTER GA <span class="label-legacy">{{ site.t[page.lang].legacy }}</span> -->
+            {{ section.title }}
+            <span class="label-deprecated">{{ site.t[page.lang].deprecated }}</span>
           </h3>
           {{ section.content | markdownify }}
           <hr />
diff --git a/docs/_steps/workflow_steps_overview.md b/docs/_steps/workflow_steps_overview.md
@@ -6,9 +6,12 @@ order: 1
 ---
 
 <div class="section-content">
+
+Steps from Apps for legacy workflows are now deprecated. Use new [custom steps](https://api.slack.com/automation/functions/custom-bolt).
+
 Workflow Steps from apps allow your app to create and process custom workflow steps that users can add using [Workflow Builder](https://api.slack.com/workflows).
 
-A workflow step is made up of three distinct user events: 
+A workflow step is made up of three distinct user events:
 
 - Adding or editing the step in a Workflow
 - Saving or updating the step's configuration
diff --git a/docs/assets/style.css b/docs/assets/style.css
@@ -117,7 +117,7 @@ span.beta {
   font-weight: 600;
 }
 
-.panel .sidebar-content ul.sidebar-section .label-legacy {
+.panel .sidebar-content ul.sidebar-section .label-deprecated {
   line-height: 1em;
   vertical-align: middle;
   color: var(--white);
@@ -321,7 +321,7 @@ td.rouge-gutter {
   width: 100%;
 }
 
-.content .section-wrapper .label-legacy {
+.content .section-wrapper .label-deprecated {
   line-height: 1em;
   vertical-align: middle;
   color: var(--white);
diff --git a/examples/workflow_steps/async_steps_from_apps.py b/examples/workflow_steps/async_steps_from_apps.py
@@ -9,6 +9,11 @@
     AsyncFail,
 )
 
+################################################################################
+# Steps from Apps for legacy workflows are now deprecated.                     #
+# Use new custom steps: https://api.slack.com/automation/functions/custom-bolt #
+################################################################################
+
 logging.basicConfig(level=logging.DEBUG)
 
 # export SLACK_SIGNING_SECRET=***
diff --git a/examples/workflow_steps/async_steps_from_apps_decorator.py b/examples/workflow_steps/async_steps_from_apps_decorator.py
@@ -11,6 +11,11 @@
     AsyncWorkflowStep,
 )
 
+################################################################################
+# Steps from Apps for legacy workflows are now deprecated.                     #
+# Use new custom steps: https://api.slack.com/automation/functions/custom-bolt #
+################################################################################
+
 logging.basicConfig(level=logging.DEBUG)
 
 # export SLACK_SIGNING_SECRET=***
diff --git a/examples/workflow_steps/async_steps_from_apps_primitive.py b/examples/workflow_steps/async_steps_from_apps_primitive.py
@@ -3,6 +3,11 @@
 from slack_sdk.web.async_client import AsyncSlackResponse, AsyncWebClient
 from slack_bolt.async_app import AsyncApp, AsyncAck
 
+################################################################################
+# Steps from Apps for legacy workflows are now deprecated.                     #
+# Use new custom steps: https://api.slack.com/automation/functions/custom-bolt #
+################################################################################
+
 logging.basicConfig(level=logging.DEBUG)
 
 # export SLACK_SIGNING_SECRET=***
diff --git a/examples/workflow_steps/steps_from_apps.py b/examples/workflow_steps/steps_from_apps.py
@@ -6,6 +6,11 @@
 from slack_bolt import App, Ack
 from slack_bolt.workflows.step import Configure, Update, Complete, Fail
 
+################################################################################
+# Steps from Apps for legacy workflows are now deprecated.                     #
+# Use new custom steps: https://api.slack.com/automation/functions/custom-bolt #
+################################################################################
+
 logging.basicConfig(level=logging.DEBUG)
 
 # export SLACK_SIGNING_SECRET=***
diff --git a/examples/workflow_steps/steps_from_apps_decorator.py b/examples/workflow_steps/steps_from_apps_decorator.py
@@ -7,6 +7,11 @@
 from slack_bolt import App, Ack
 from slack_bolt.workflows.step import Configure, Update, Complete, Fail, WorkflowStep
 
+################################################################################
+# Steps from Apps for legacy workflows are now deprecated.                     #
+# Use new custom steps: https://api.slack.com/automation/functions/custom-bolt #
+################################################################################
+
 logging.basicConfig(level=logging.DEBUG)
 
 # export SLACK_SIGNING_SECRET=***
diff --git a/examples/workflow_steps/steps_from_apps_primitive.py b/examples/workflow_steps/steps_from_apps_primitive.py
@@ -5,6 +5,11 @@
 
 from slack_bolt import App, Ack
 
+################################################################################
+# Steps from Apps for legacy workflows are now deprecated.                     #
+# Use new custom steps: https://api.slack.com/automation/functions/custom-bolt #
+################################################################################
+
 logging.basicConfig(level=logging.DEBUG)
 
 # export SLACK_SIGNING_SECRET=***
diff --git a/slack_bolt/app/app.py b/slack_bolt/app/app.py
@@ -3,6 +3,7 @@
 import logging
 import os
 import time
+import warnings
 from concurrent.futures import Executor
 from concurrent.futures.thread import ThreadPoolExecutor
 from http.server import SimpleHTTPRequestHandler, HTTPServer
@@ -659,7 +660,13 @@ def step(
         save: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None,
         execute: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None,
     ):
-        """Registers a new Workflow Step listener.
+        """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
+        Registers a new Workflow Step listener.
+
         Unlike others, this method doesn't behave as a decorator.
         If you want to register a workflow step by a decorator, use `WorkflowStepBuilder`'s methods.
 
@@ -688,6 +695,13 @@ def step(
             save: The function for handling configuration in the Workflow Builder
             execute: The function for handling the step execution
         """
+        warnings.warn(
+            (
+                "Steps from Apps for legacy workflows are now deprecated. "
+                "Use new custom steps: https://api.slack.com/automation/functions/custom-bolt"
+            ),
+            category=DeprecationWarning,
+        )
         step = callback_id
         if isinstance(callback_id, (str, Pattern)):
             step = WorkflowStep(
diff --git a/slack_bolt/app/async_app.py b/slack_bolt/app/async_app.py
@@ -3,6 +3,7 @@
 import os
 import time
 from typing import Optional, List, Union, Callable, Pattern, Dict, Awaitable, Sequence, Any
+import warnings
 
 from aiohttp import web
 
@@ -689,7 +690,12 @@ def step(
         execute: Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]] = None,
     ):
         """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
         Registers a new Workflow Step listener.
+
         Unlike others, this method doesn't behave as a decorator.
         If you want to register a workflow step by a decorator, use `AsyncWorkflowStepBuilder`'s methods.
 
@@ -717,6 +723,13 @@ def step(
             save: The function for handling configuration in the Workflow Builder
             execute: The function for handling the step execution
         """
+        warnings.warn(
+            (
+                "Steps from Apps for legacy workflows are now deprecated. "
+                "Use new custom steps: https://api.slack.com/automation/functions/custom-bolt"
+            ),
+            category=DeprecationWarning,
+        )
         step = callback_id
         if isinstance(callback_id, (str, Pattern)):
             step = AsyncWorkflowStep(
diff --git a/slack_bolt/workflows/step/async_step.py b/slack_bolt/workflows/step/async_step.py
@@ -43,7 +43,12 @@ def __init__(
         app_name: Optional[str] = None,
         base_logger: Optional[Logger] = None,
     ):
-        """This builder is supposed to be used as decorator.
+        """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
+        This builder is supposed to be used as decorator.
 
             my_step = AsyncWorkflowStep.builder("my_step")
             @my_step.edit
@@ -80,7 +85,13 @@ def edit(
         middleware: Optional[Union[Callable, AsyncMiddleware]] = None,
         lazy: Optional[List[Callable[..., Awaitable[None]]]] = None,
     ):
-        """Registers a new edit listener with details.
+        """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
+        Registers a new edit listener with details.
+
         You can use this method as decorator as well.
 
             @my_step.edit
@@ -127,7 +138,13 @@ def save(
         middleware: Optional[Union[Callable, AsyncMiddleware]] = None,
         lazy: Optional[List[Callable[..., Awaitable[None]]]] = None,
     ):
-        """Registers a new save listener with details.
+        """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
+        Registers a new save listener with details.
+
         You can use this method as decorator as well.
 
             @my_step.save
@@ -174,7 +191,13 @@ def execute(
         middleware: Optional[Union[Callable, AsyncMiddleware]] = None,
         lazy: Optional[List[Callable[..., Awaitable[None]]]] = None,
     ):
-        """Registers a new execute listener with details.
+        """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
+        Registers a new execute listener with details.
+
         You can use this method as decorator as well.
 
             @my_step.execute
@@ -215,7 +238,12 @@ async def _wrapper(*args, **kwargs):
         return _inner
 
     def build(self, base_logger: Optional[Logger] = None) -> "AsyncWorkflowStep":
-        """Constructs a WorkflowStep object. This method may raise an exception
+        """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
+        Constructs a WorkflowStep object. This method may raise an exception
         if the builder doesn't have enough configurations to build the object.
 
         Returns:
@@ -309,6 +337,10 @@ def __init__(
         base_logger: Optional[Logger] = None,
     ):
         """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+
         Args:
             callback_id: The callback_id for this workflow step
             edit: Either a single function or a list of functions for opening a modal in the builder UI
@@ -350,6 +382,11 @@ def builder(
         callback_id: Union[str, Pattern],
         base_logger: Optional[Logger] = None,
     ) -> AsyncWorkflowStepBuilder:
+        """
+        Deprecated:
+            Steps from Apps for legacy workflows are now deprecated.
+            Use new custom steps: https://api.slack.com/automation/functions/custom-bolt
+        """
         return AsyncWorkflowStepBuilder(callback_id, base_logger=base_logger)
 
     @classmethod
diff --git a/slack_bolt/workflows/step/step.py b/slack_bolt/workflows/step/step.py
