Commit 0961791d authored by Mike Jang's avatar Mike Jang

Merge branch 'sidekiq-remove-argument-documentation' into 'master'

Docs: Update Sidekiq development guide

See merge request gitlab-org/gitlab!40140
parents 725c66a2 55cb9e7a
......@@ -615,42 +615,51 @@ Jobs need to be backward and forward compatible between consecutive versions
of the application. Adding or removing an argument may cause problems
during deployment before all Rails and Sidekiq nodes have the updated code.
#### Remove an argument
#### Deprecate and remove an argument
**Do not remove arguments from the `perform` function.**. Instead, use the
following approach:
**Before you remove arguments from the `perform_async` and `perform` methods.**, deprecate them. The
following example deprecates and then removes `arg2` from the `perform_async` method:
1. Provide a default value (usually `nil`) and use a comment to mark the
argument as deprecated
1. Stop using the argument in `perform_async`.
1. Ignore the value in the worker class, but do not remove it until the next
major release.
argument as deprecated in the coming minor release. (Release M)
In the following example, if you want to remove `arg2`, first set a `nil` default value,
and then update locations where `ExampleWorker.perform_async` is called.
```ruby
class ExampleWorker
# Keep arg2 parameter for backwards compatibility.
def perform(object_id, arg1, arg2 = nil)
# ...
end
end
```
```ruby
class ExampleWorker
def perform(object_id, arg1, arg2 = nil)
# ...
end
end
```
1. One minor release later, stop using the argument in `perform_async`. (Release M+1)
```ruby
ExampleWorker.perform_async(object_id, arg1)
```
1. At the next major release, remove the value from the worker class. (Next major release)
```ruby
class ExampleWorker
def perform(object_id, arg1)
# ...
end
end
```
#### Add an argument
There are two options for safely adding new arguments to Sidekiq workers:
1. Set up a [multi-step deployment](#multi-step-deployment) in which the new argument is first added to the worker
1. Set up a [multi-step deployment](#multi-step-deployment) in which the new argument is first added to the worker.
1. Use a [parameter hash](#parameter-hash) for additional arguments. This is perhaps the most flexible option.
##### Multi-step deployment
This approach requires multiple merge requests and for the first merge request
to be merged and deployed before additional changes are merged.
This approach requires multiple releases.
1. In an initial merge request, add the argument to the worker with a default
value:
1. Add the argument to the worker with a default value (Release M).
```ruby
class ExampleWorker
......@@ -660,16 +669,28 @@ to be merged and deployed before additional changes are merged.
end
```
1. Merge and deploy the worker with the new argument.
1. In a further merge request, update `ExampleWorker.perform_async` calls to
use the new argument.
1. Add the new argument to all the invocations of the worker (Release M+1).
```ruby
ExampleWorker.perform_async(object_id, new_arg)
```
1. Remove the default value (Release M+2).
```ruby
class ExampleWorker
def perform(object_id, new_arg)
# ...
end
end
```
##### Parameter hash
This approach will not require multiple deployments if an existing worker already
This approach will not require multiple releases if an existing worker already
utilizes a parameter hash.
1. Use a parameter hash in the worker to allow for future flexibility:
1. Use a parameter hash in the worker to allow future flexibility.
```ruby
class ExampleWorker
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment