Add latest changes from gitlab-org/gitlab@master

1 files changed, 55 insertions, 6 deletions

diff --git a/doc/development/sidekiq/compatibility_across_updates.md b/doc/development/sidekiq/compatibility_across_updates.md
index cfb709d9110..e61e1420717 100644
--- a/doc/development/sidekiq/compatibility_across_updates.md
+++ b/doc/development/sidekiq/compatibility_across_updates.md
@@ -123,14 +123,63 @@ uses a parameter hash.
     end
     ```
 
-## Removing workers
+## Removing worker classes
 
-Try to avoid removing workers and their queues in minor and patch
-releases.
+To remove a worker class, follow these steps over two minor releases:
 
-During online update instance can have pending jobs and removing the queue can
-lead to those jobs being stuck forever. If you can't write migration for those
-Sidekiq jobs, please consider removing the worker in a major release only.
+### In the first minor release
+
+1. Remove any code that enqueues the jobs.
+
+    For example, if there is a UI component or an API endpoint that a user can interact with that results in the worker instance getting enqueued, make sure those surface areas are either removed or updated in a way that the worker instance is no longer enqueued. 
+
+    This ensures that instances related to the worker class are no longer being enqueued.
+
+1. Ensure both the frontend and backend code no longer relies on any of the work that used to be done by the worker.
+1. In the relevant worker classes, replace the contents of the `perform` method with a no-op, while keeping any arguments in tact. 
+
+    For example, if you're working with the following `ExampleWorker`:
+
+      ```ruby
+        class ExampleWorker
+          def perform(object_id)
+            SomeService.run!(object_id)
+          end
+        end
+      ```
+    
+    Implementing the no-op might look like this:
+
+      ```ruby
+        class ExampleWorker
+          def perform(object_id); end
+        end
+      ```
+
+    By implementing this no-op, you can avoid unnecessary cycles once any deprecated jobs that are still enqueued eventually get processed.
+
+1. In a separate merge request, because it's a migration, consider using the `sidekiq_remove_jobs` helper migration method in a **post-deployment migration**:
+
+    ```ruby
+    class RemoveMyDeprecatedWorkersJobInstances < Gitlab::Database::Migration[2.0]
+      DEPRECATED_JOB_CLASSES = %w[
+        MyDeprecatedWorkerOne
+        MyDeprecatedWorkerTwo
+      ]
+
+      def up
+        sidekiq_remove_jobs(job_klasses: DEPRECATED_JOB_CLASSES)
+      end
+
+      def down
+        # This migration removes any instances of deprecated workers and cannot be undone.
+      end
+    end
+    ```
+
+#### In a subsequent, separate minor release
+
+1. Delete the worker class file and follow the guidance in our [Sidekiq queues documentation](../sidekiq/index.md#sidekiq-queues) around running Rake tasks to regenerate/update related files.
 
 ## Renaming queues