Improvements to ActiveRecord::Rollback docs

[jjb]

The main problem I wanted to solve is that the "Call tech support" message in the example is
confusing in this scenario, because it's addressing the user, but the user will never see it.
I'm not sure if I'm not understanding something, or maybe this was copy/pasted from
another example years ago.

Here I remove that and also expand the docs, hopefully illustrating the concept better.

Any and all feedback on copy, phrasing, formatting, examples, is welcome!

[p8]

Hey @jjb, thanks for the PR!

I can see how the "Call tech support" line is confusing.
The example is getting a lot complexer though now.

What do you think about adding the If this fails, user gets generic 500 behavior comment above the book.save!
and removing the "Call tech support" string like you did?

[jjb]

done - if that looks good i can squish the two commits

The example is getting a lot complexer though now

by this do you mean it's difficult to understand, or it's not emblematic of intended use case, or something else?

I think the docs currently in main are not emblematic of a typical use case, if you agree i wonder if we can improve the docs without making them too complex.

[p8]

@jjb adding the Author and Stats models makes things more complex.
Also, while the different responses ("rendering" and "redirecting") might be more realistic, they add more complexity that maybe isn't relevant to the example.
PRs are always welcome. If there is an another example you'd like to change we can discuss it another PR.

[p8]

This looks good to me! 🚢
Please squash the commits.

[jjb]

@p8 squashed

[jjb]

@p8 okay, done

would you consider replacing the today_is_friday? joke example for when the rollback is used? I feel it's not a good way to explain a possible real world use case and the jokiness creates a cognitive speed bump while trying to understand.

[p8]

I’m okay with that. I like some light hearted reading, but it shouldn’t be at the cost of understandability.

Maybe we should show the example in a model instead of a controller. An Order that requires the Book to be in the inventory? This allows us to skip all the rendering logic and use a more realistic example?

[jjb]

in that scenario, which operations should raise and which operations should continue on?

[rails-bot]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
Thank you for your contributions.

[jjb]

Hi @p8 - if you have time and interest to answer my question I can maybe put something together, thanks!

[p8]

Hi @jjb sorry for the late reply 😞

Maybe we can render a different flash depending on whether the book was saved?
What do you think about something like:

  #   class BooksController < ActionController::Base
  #     def create
  #       book = Book.new(params[:book])
  #       Book.transaction do
  #         book.save!
  #         # If this fails, we rollback this transaction and pass on the exception.
  #         # The user gets generic 500 behavior.
  #         Stats.create!(type: 'book_purchase')
  #         if today_is_friday?
  #           # The system must fail on Friday so that our support department
  #           # won't be out of job. We silently rollback this transaction
  #           # without telling the user.
  #           raise ActiveRecord::Rollback
  #         end
  #       end
  #       # ActiveRecord::Rollback is the only exception that won't be passed on
  #       # by ActiveRecord::Base.transaction, so this will still be reached
  #       # even on Friday.
  #       if book.persisted?
  #         redirect_to root_url, notice: "Book purchased"
  #       else
  #         redirect_to root_url, alert: "Call tech support!"
  #       end
  #     end

[jjb]

thanks for looping back - i won't be able to work on this unfortunately - maybe someone else can pick it up and work with what i've suggested