Add deprecation notice for Time.now

[straight-shoota]

This is a follow up on #5346 and adds the following error message for Time.now, guiding the user to fixing this breaking change:

`Time.now` has been removed in Crystal 0.28.0, use `Time.local` or `Time.utc` instead.

More information on this change: https://github.com/crystal-lang/crystal/issues/5346

[ysbaddaden]

Sigh, sometimes I wish we'd keep a few aliases. I already fathom how much time I'll lose with Time now failing to compile and have to dig to find Time.local that I'll never remember...

[straight-shoota]

I'm not strictly opposed to make Time.now an alias. I don't think it would hurt much and improve quality of life for developers accustomed to Ruby's Time.now.
And there are already a few other precedents, where we have essentially aliases.

[straight-shoota]

Please note the prior discussion about alias/deprecation in #5346 after the merge.

[bcardiff]

I would vouch for a deprecation cycle and a --check compiler option. There is little gain with this compile time error.

When possible the author of shards should be able to support two crystal versions at the same time to simplify migration paths.

[straight-shoota]

Following the discussion here and in crystal-lang/crystal-mysql#73, I've changed this PR to re-add Time.now for 0.28.0 as an alias to Time.local. It doesn't hurt to keep the alias for now and having a grace period makes it easier to migrate, improve developer happiness.

[j8r]

Only changing the method to an alias without any deprecation warning, and probably most users who don't read carefully the changelog won't notice the deprecation, even if it appears in the API docs.

[straight-shoota]

@j8r Yes, that's what we want. For now at least. This is a breaking change, but given it's widespread use, it shouldn't immediately break every code. Let's give people time to adapt and keep support for both .local and .now simultaneously at least for one release (maybe even more).

I'd like to keep .now usable at least for 0.28.0. After that is released we can consider to completely remove it, add a compile time deprecation message (maybe already with compiler support for @[Deprecated]), postpone to the next release, or even decide that we want to keep this as an exceptional alias indefinitely.

[asterite]

@straight-shoota What we can do is leave the alias but still output a warning at compile-time. The warning is annoying but your code will work. But because it's annoying people will change the new call to local or utc, and so when we introduce the breaking change people would have adapted already.

What do you think?

[straight-shoota]

We had similar discussions about compiler warnings before, but I think it was largely agreed that the compiler should either work or fail, and don't print warnings.

Anyway, I'd say it's fine to merge this as is, adding a deprecation notice in the API docs. Let's see what the suggested compiler check feature brings and continue this discussion afterwards.

[straight-shoota]

Added @[Deprecated] annotations from #7596.

Will only work after 0.28 is released.

[bcardiff]

@straight-shoota we can do

  {% if compare_versions(Crystal::VERSION, "0.28.0-0") >= 0 %}
    @[Deprecated("....")]
  {% end %}
  def foo
  end

[straight-shoota]

Let's just add that after 0.28.0. this PR can be merged without.

[bcardiff]

But then the deprecation will exist from 0.29.
We are used for the std lib to have some checks that apply from the next release

[straight-shoota]

I don't see what's the benefit of adding a version guard for a deprecation annotation instead of simply adding the deprecation annotation after the next release?

[bcardiff]

That it could be removed in 0.29.0. That's the only benefit I see. Since we are adding it again for 0.28 for a migration path I thought we wanted to remove it as early as possible.

[asterite]

I'm thinking that we can add the annotation as a source file too in the top level, and even document it. Then we can use it right away and the next compiler will pick it up. What do you think? /cc @bcardiff

We should do the same too for other attributes (link, packed, etc)

[bcardiff]

We are ready for a rebase and remove the deprecated comment here and in the other method.

[straight-shoota]

Forgot to push 🕺