Best practice to mark deprecated code in Ruby?

Question

For almost all cases, depending on a library or metaprogramming for a deprecation is overkill. Just add a comment to the rdoc and call the Kernel#warn method. For example:

class Foo
  # <b>DEPRECATED:</b> Please use <tt>useful</tt> instead.
  def useless
    warn "[DEPRECATION] `useless` is deprecated.  Please use `useful` instead."
    useful
  end

  def useful
    # ...
  end
end

---

If you're using Yard instead of rdoc, your doc comment should look like this:

# @deprecated Please use {#useful} instead

Lastly, if you adhere to tomdoc, make your comment look like this:

# Deprecated: Please use `useful` instead

Deprecated: Indicates that the method is deprecated and will be removed in a future version. You SHOULD use this to document methods that were Public but will be removed at the next major version.

---

Also, don't forget to remove the deprecated method in some future (and properly semver'd) release. Don't make the same mistakes that the Java libraries did.

Ruby Standard Library has a module with the warning logic: https://ruby-doc.org/stdlib/libdoc/rubygems/rdoc/Gem/Deprecate.html. I tend to prefer it to maintain my deprecation messages in a "standard" way:

# my_file.rb

class MyFile
  extend Gem::Deprecate

  def no_more
    close
  end
  deprecate :no_more, :close, 2015, 5

  def close
    # new logic here
  end
end

MyFile.new.no_more
# => NOTE: MyFile#no_more is deprecated; use close instead. It will be removed on or after 2015-05-01.
# => MyFile#no_more called from my_file.rb:16.

Note that with this approach you will gain for free information about where the call took place.

Using ActiveSupport:

class Player < ActiveRecord::Base
  def to_s
    ActiveSupport::Deprecation.warn('Use presenter instead')
    partner_uid
  end
end

Warnings are turned off in production environment by default

If you want to be mean (under the guile of being helpful) you can print out the first line of the callstack during a warning to let devs know where they are using a deprecated call.

This is mean because I'm pretty sure it's a performance-hit.

warn Kernel.caller.first + " whatever deprecation message here"

When used correctly, this will include the absolute path to the file and line where the deprecated call was used. More information about Kernel::caller is available here