[ci skip] Add warning about deduplication of after_xxx_commit shortcuts

[ConfusedVorlon]

Motivation / Background

I'm not the first person to be bitten by deduplication of after_xxx_commit shortcuts.

#40648
#51171

Detail

Adds documentation to warn about this.

[vipulnsward]

Thanks!

[zzak]

This is already documented here:
https://edgeguides.rubyonrails.org/active_record_callbacks.html#transaction-callbacks

Using both after_create_commit and after_update_commit with the same method name will only allow the last callback defined to take effect, as they both internally alias to after_commit which overrides previously defined callbacks with the same method name.

[ConfusedVorlon]

@zzak So it is - however people don't necessarily check/remember that guide.

Indeed, this bit me because I was reading the method's docs, rather than thinking to check the overview guide for this.

Personally, I don't see any problem with duplicating a warning so that people can get the info at the method definition as well as if they RTM.

[zzak]

@ConfusedVorlon Thanks for your PR, and apologies for not getting feedback sooner.

I would prefer something in the form as I mentioned here: #51886 (comment)

[ConfusedVorlon]

I gotta say - this does not fill me with enthusiasm for trying to improve the docs.
I saw a problem, I offered a fix, it was merged.

Now you think that the red warning in the guide is sufficient - and you remove the warnings at the method definition.

If you think that's better - so be it.
To my mind - the big red warning in the guide only emphasises the need for warnings at the method definition.

Personally, I would suggest that if you want to improve the style of documentation after changes are committed, then a pull request would be a better solution than a revert.

[zzak]

I disagree that there needs to be a warning at every method definition, but open to adding a note in the top-level ClassMethods overview.

This is consistent with the rest of our documentation, please show me if that is not the case.

As for the method naming, for example we use after_*_commit in the guides where we typically use wildcard notation for dynamic methods (See: Dirty).

It's on me because if I could have reviewed your PR sooner, I would have given you that guidance sooner and hopefully we could gain some momentum together.

If you want to submit the other PR feel free to ping me.

[ConfusedVorlon]

If you want to submit the other PR feel free to ping me.

Nope. I'm done.
I'll remember this gotcha. The next person will have to find out the hard way.

btw - this wasn't submitted out of nowhere. I did ask for advice on format first.
#51171