Deprecate the behavior of AR::Dirty inside of after_(create|update|save) callbacks

[sgrif]

We pretty frequently get bug reports that "dirty is broken inside of after callbacks". Intuitively they are correct. You'd expect Model.after_save { puts changed? }; model.save to do the same thing as model.save; puts model.changed?, but it does not.

However, changing this goes much farther than just making the behavior more intuitive. There are a ton of places inside of AR that can be drastically simplified with this change. Specifically, autosave associations, timestamps, touch, counter cache, and just about anything else in AR that works with callbacks have code to try to avoid "double save" bugs which we will be able to flat out remove with this change.

We introduce two new sets of methods, both with names that are meant to be more explicit than dirty. The first set maintains the old behavior, and their names are meant to center that they are about changes that occurred during the save that just happened. They are equivalent to previous_changes when called outside of after callbacks, or once the deprecation cycle moves.

The second set is the new behavior. Their names imply that they are talking about changes from the database representation. The fact that this is what we really care about became clear when looking at BelongsTo.touch_record when tests were failing. I'm unsure that this set of methods should be in the public API. Outside of after callbacks, they are equivalent to the existing methods on dirty.

I am not married to any of the method names. Please bikeshed the shit out of them, I am open to alternatives.

Dirty itself is not deprecated, nor are the methods inside of it. They will only emit the warning when called inside of after callbacks. The scope of this breakage is pretty large, but the migration path is simple. Given how much this can improve our codebase, and considering that it makes our API more intuitive, I think it's worth doing.

Unresolved questions

Do we want the "new behavior" methods to be in the public API at all? They are straight aliases to the existing methods in dirty after 5.2/6.0. However, since we get these bug reports, someone probably does want the new behavior today.

Still left todo

I need to improve the commit messages, and move the deprecation warning up to the caller of mutation_tracker to include the exact method to call instead. The current implementation is also emitting deprecation warnings in places where the calls are valid. This will be fixed by moving the warning to the right place.

[sgrif]

/cc @matthewd @rafaelfranca This is not ready to merge, but the remaining changes I have to make are to commit messages and where the deprecation warning is emitted, which shouldn't affect the discussion around this change.

[olivierlacan]

Wouldn't changes_to_be_saved? be more coherent with attribute_change_to_be_saved?

[sgrif]

The goal was to make the difference between some of the methods more clear. Do you think that model.changes_to_be_saved? reads clearly enough? Compared to model.has_changes_to_save?

[olivierlacan]

I feel like I need to wrap my mind around the name changes in the public API outside of the code to fully focus on their semantics (I hope that's not weird and distracting from the PR convo). I hope this helps.

Legend:

• => in the meaning column means there's a non-boolean return value
• empty columns in Prior Name mean the method didn't exist before
• * before a new method name means it's an alias to the prior method

Prior Name	New Name	Meaning
attribute_was(attr_name)	*attribute_in_database(attr_name)	current database value of attribute
attribute_change(attr_name)	*attribute_change_to_be_saved	=> the changed value for attribute
attribute_changed?(attr_name)	*will_save_change_to_attribute?(attr_name)	was attribute modified since last save
	attribute_before_last_save(attr_name)	=> attribute value from before last save
changed	*changed_attribute_names_to_save	=> name of attributes with changed values since last save
changes	*changes_to_save	=> the changes to be saved to DB
changed?	*has_changes_to_save?	are there any changes to be saved to the DB?
changed_attributes	*attributes_in_database	=> Hash of attribute names & new unsaved values
changed?	has_changes_to_save?	record has unsaved changes
	saved_changes?	did last save change record attributes?
	saved_changes	=> Hash of all changes in last save
	saved_change_to_attribute?(attr_name)	did attribute change when record last saved?
	saved_change_to_attribute(attr_name)	=> array of original & saved value from last save

@sgrif Please feel free to edit the above to correct any incorrect meaning.

[nateberkopec]

Are those aliases intended to be public? Wasn't sure. If they are public, I agree, they were sort of hard to wrap my head around.

[sgrif]

Going to move forward with this change. If anyone has suggested improvements to the names of the new methods, please open a PR.

[krtschmr]

@sgrif what happened to attribute_changed? like after_save :analyze_file_async, if: :file_changed?

i can't figure the new naming. this looks ugly to me though: if: ->{ saved_change_to_attribute?(:file?) }

why we don't make if : :file_was_updated? so we make

def #{attribute}_was_updated?
  saved_change_to_attribute?(attr)
end

then we can use it `after_save :analyze_file_async, if: :file_was_updated?

[dsandstrom]

Are the new method names documented anywhere besides here? Maybe update http://api.rubyonrails.org/classes/ActiveModel/Dirty.html .