README.md in isolator-0.3.0 vs README.md in isolator-0.4.0
- old
+ new
@@ -129,10 +129,14 @@
# Enable back
Isolator.adapters.http.enable!
```
+### Fix Offenses
+
+For the actions that should be executed only after successful transaction commit (which is mostly always so), you can try to use the `after_commit` callback from [after_commit_everywhere] gem (or use native AR callback in models if it's applicable).
+
### Ignore Offenses
Since Isolator adapter is just a wrapper over original code, it may lead to false positives when there is another library patching the same behaviour. In that case you might want to ignore some offenses.
Consider an example: we use Sidekiq along with [`sidekiq-postpone`](https://github.com/marshall-lee/sidekiq-postpone)–gem that patches `Sidekiq::Client#raw_push` and allows you to postpone jobs enqueueing (e.g. to enqueue everything when a transaction is commited–we don't want to raise exceptions in such situation).
@@ -143,10 +147,26 @@
Isolator.adapters.sidekiq.ignore_if { Thread.current[:sidekiq_postpone] }
```
You can add as many _ignores_ as you want, the offense is registered iff all of them return false.
+### Using with legacy Rails codebases
+
+If you already have a huge Rails project it can be a tricky to turn Isolator on because you'll immediately get a lot of failed specs. If you want to fix detected issues one by one, you can list all of them in the special file `.isolator_todo.yml` in a following way:
+
+```
+sidekiq:
+ - app/models/user.rb:20
+ - app/models/sales/**/*.rb
+```
+
+All the exceptions raised in the listed lines will be ignored.
+
+### Using with legacy Ruby codebases
+
+If you are not using Rails, you'll have to load ignores from file manually, using `Isolator#load_ignore_config`, for instance `Isolator.load_ignore_config("./config/.isolator_todo.yml")`
+
## Custom Adapters
An adapter is just a combination of a _method wrapper_ and lifecycle hooks.
Suppose that you have a class `Danger` with a method `#explode`, which is not safe to be run within a DB transaction. Then you can _isolate_ it (i.e., register with Isolator):
@@ -155,14 +175,14 @@
# The first argument is a unique adapter id,
# you can use it later to enable/disable the adapter
#
# The second argument is the method owner and
# the third one is a method name.
-Isolotar.isolate :danger, Danger, :explode, **options
+Isolator.isolate :danger, Danger, :explode, options
# NOTE: if you want to isolate a class method, use signleton_class instead
-Isolator.isolate :danger, Danger.singleton_class, :explode, **options
+Isolator.isolate :danger, Danger.singleton_class, :explode, options
```
Possible `options` are:
- `exception_class` – an exception class to raise in case of offense
- `exception_message` – custom exception message (could be specified without a class)
@@ -187,5 +207,6 @@
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
[Sniffer]: https://github.com/aderyabin/sniffer
[uniform_notifier]: https://github.com/flyerhzm/uniform_notifier
+[after_commit_everywhere]: https://github.com/Envek/after_commit_everywhere