Deprecate public visibility of order#finalize!

[waiting-for-dev]

Description

The only invocation of order#finalize! comes from the state machine
transaction to complete:

solidus/core/lib/spree/core/state_machines/order.rb

Line 122 in e18f345

after_transition to: :complete, do: :finalize!

Calling it standalone should not be encouraged, as all the safety checks
implemented as before hooks would be skipped.

As a deprecation strategy, we're renaming the old #finalize! method to
#finalize and updating the state machine to call the latter. In turn,
#finalize! deprecates but still delegates to the new method.

Consequently, we're updating the test suite only to reference the public
API. I.e, Spree::Order#complete!. That has forced us to refactor some
tests. From core/spec/models/spree/order/finalizing_spec.rb:

• should set completed_at: Before being called with :completed_at
  as an argument, touch is called by the state machine transition. It's
  easier if we just assert on the field value.

• should sell inventory units: During the transaction, the shipment's
  #object_id gets changed, so we can't longer assert on those instances.
  Instead, we test the actual behavior. The assertion about
  #update_state is already covered in the following test.

• should change the shipment state to ready if order is paid: We take
  the ocassion to assert on the actual behavior.

• should freeze all adjustments: There're other methods called on the
  collection of adjustments that are not covered by the double. It's
  easier to test the actual behavior.

Besides, we're moving some tests about the order completion from
order_spec.rb to finalizing_spec.rb, also adapting them to test
#complete! instead of finalize!. These added tests explain the
removal of others which were simple duplication.

Checklist:

• I have followed Pull Request guidelines
• I have added a detailed description into each commit message
• I have updated Guides and README accordingly to this change (if needed)
• I have added tests to cover this change (if needed)
• I have attached screenshots to this PR for visual changes (if needed)

[spaghetticode]

Thanks Marc, I especially ❤️ the removal of some expect to receive on the object under testing in favor of testing the real behavior 🎉

[jarednorman]

Should we consider this a breaking change, mark it for the next major release?

[waiting-for-dev]

Should we consider this a breaking change, mark it for the next major release?

Good point. I've updated the code with the following:

• Restored public visibility of order#finalized!.
• Added # @api private yard tag.
• Added a TODO: note for 4.0.

I think this way we can go ahead and merge it, leaving for the future the actual deprecation.

[waiting-for-dev]

After a meeting with the Core Team, we have decided to do a smarter deprecation by renaming the current #finalize! to #finalize, calling the latter from the state machine, and rendering a deprecation message, while still forwarding to the new method, in the former. I'll work on it shortly.

[jarednorman]

Cool, that makes sense to me.

[waiting-for-dev]

Done! cc @spaghetticode @kennyadsl