experimental and deprecated interface

[gefjon]

It would be nice, both in the library and in user code, to be able to mark definitions as either experimental or deprecated, and have the compiler issue warnings of appropriate levels when they're used. I envision something like:

(experimental "github.com/coalton-lang/coalton/issues/SOME-ISSUE-NUMBER")
(declare foo (Bar -> Baz))
(define (foo bar) (baz bar))

;; early deprecations
(deprecated style-warning "github.com/coalton-lang/coalton/pull/SOME-PR-NUMBER"
  "makeFoo renamed to make-foo")
(declare makeFoo (Bar -> Baz))
(define makeFoo make-foo)

;; late deprecations
(deprecated warning "github.com/coalton-lang/coalton/pull/SOME-PR-NUMBER"
  "call-with-bar offers no way to handle errors; try-with-bar should be preferred")
(declare call-with-bar ((Bar -> :any) -> Bar -> :any))
(define (call-with-bar thunk bar)
  (unwrap (try-with-bar thunk bar)))

;; removed definitions
(deprecated error "github.com/coalton-lang/coalton/pull/SOME-PR-NUMBER"
  "unsound-garbage has been removed")
(define (unsound-garbage) (error "unsound-garbage has been removed"))

This syntax is not great, but I think it gets across the key points:

• Experimental APIs should have some way of linking to a discussion of the API and its pathway to stabilization.
• Using an experimental API should issue a style-warning which includes the name of the experimental API, the callsite and the discussion link.
  • Probably the compiler should signal exactly one such warning for each experimental API used, ideally including info on all the used callsites.
  • Possibly there should be some way for user code to opt out of the style-warning, but that seems like less of a necessity to me.
• Deprecated APIs should have a way of describing what stage of deprecation they are in:
  • Early deprecation should issue a style-warning, which will print a note to users but not break ASDF builds.
  • Late deprecation should issue a warning, which will break ASDF builds but can be ignored via an interactive restart.
  • Full deprecation/removal should issue a non-recoverable error.
• Deprecated APIs should have some way of linking to a discussion, as with experimental APIs.
• Deprecated APIs should also have some way of describing why the API was deprecated and what its replacements are.