Crystal: Compile-time deprecation warnings

[j8r]

There are no proper way to deprecate methods/objects.
The common way is to add a comment like # TODO: Remove after 0.28.0 but the end user won't be informed of this future breaking-change when compiling its program. (S)he will only notice the missing object/methods when using the new release that remove them, and has to read the CHANGELOG to figure out what breaking-change is the source of this, and what to do.

Solution

C# has the Obsolete annotation for deprecation, java has @Deprecated

An annotation can be used to deprecate method and objects, along with a deprecation message:

@[Deprecated("will be removed in 0.28.0, use `new_method` instead")]
def old_method
end

This will print a colored deprecation notice like: Deprecated: old_method: will be removed in 0.28.0, use `new_method` instead"

This could also add a deprecation message below the method in the generated docs.

[RX14]

This can be - and has been - done by putting

def old_method
  {{ puts "old_method is depecated and will be removed in xxx, use yyy" }}
end

see https://github.com/crystal-lang/crystal/pull/3563/files#diff-4760ade465a047460c75394908828da7R377

I'm not so sure we need a better solution for this right now, but later (close to 1.0) adding one will help external tooling.

[j8r]

I guess we can consider this issue solved with https://github.com/crystal-lang/crystal/pull/7661 and all the other PRs @bcardiff :smile:
This functionality was implemented faster than I thought. A sign that Crystal is gaining stability and approaching to 1.0?

[straight-shoota]

Quick adoption of new features is not necessarily a sign of stability 😝

And it's not complete yet. Discussion continues in #7655 👍