I was reading the docs for TimeWithZone (ActiveSupport::TimeWithZone) and noticed that two different methods can be used to add an interval: +(other) and since(other).
I ran some manual tests (copied below) and found that the two methods return the same result in almost every case.
The only case where they differ is when TimeWithZone wraps a DateTime and the "other" value passed to "since" is in a form like "1.month":
dt = DateTime.new(2014, 12, 01, 22, 00, 00).in_time_zone dt + 1.month # => Thu, 01 Jan 2015 17:00:00 EST -05:00 dt.since 1.month # => Wed, 31 Dec 2014 17:00:00 EST -05:00
However, this usage of "since" is explicitly discouraged by the documentation of DateTime#since (rails/calculations.rb at main · rails/rails · GitHub):
# Returns a new DateTime representing the time a number of seconds since the # instance time. Do not use this method in combination with x.months, use # months_since instead!
And indeed, following this recommendation the correct result is returned:
dt.months_since 1 => Thu, 01 Jan 2015 17:00:00 EST -05:00
Therefore, my proposal is to remove the method definition of TimeWithZone#since and instead replace it with a simple alias_method :since, :+
The rationale is that the only case where they differ is a case that is explicitly discouraged as "wrong". If you think this is a good idea that will make the code clearer to understand, then I will open a PR with a set of tests that demonstrate that the two methods are equivalent in every other case.
Thanks!