Rolling deprecation support

[eed3si9n]

For a contained ecosystem, rolling deprecation feature might be useful.

type Greeting {
  value: String!
  x: Int @since("0.2.0") @deprecated("0.3.0") @remove("0.4.0")
  number: Long @since("0.3.0")
}

This could generate

object Greeting {
  // 0.0.0
  def apply(value: String): Greeting = new Greeting(value, None, None)
  // 0.2.0
  @deprecated
  def apply(value: String, x: Int): Greeting = new Greeting(value, Some(x), None)
  // 0.3.0
  def apply(value: String, number: Long): Greeting = new Greeting(value, None, Some(number))
}

Once 0.4.0 is reached, remove the field altogether:

object Greeting {
  // 0.0.0
  def apply(value: String): Greeting = new Greeting(value, None)
  // 0.2.0
  def apply(value: String, x: Int): Greeting = Macro.restligeist("0.2.0 apply no longer exists.")
  // 0.3.0
  def apply(value: String, number: Long): Greeting = new Greeting(value, Some(number))
}

[dwijnand]

Why doesn't 'x' appear in 0.3.0 apply? When is "0.4.0 reached"?

[eed3si9n]

Added @deprecated("0.3.0") to denote when x became deprecated.
"0.4.0" happens either by some more annotation of introducing a field that has 0.4.0.

[dwijnand]

I think it would be simpler to just remove the field from the definition when working towards 0.4.0.

[dwijnand]

Being able to deprecate fields is good though. But it should generate deprecation annotations that include a "since" version and a message.

What if there are multiple fields to deprecate? They need to all be annotated and all share the same deprecation message. What could be a lot of duplication.

[eed3si9n]

Added

  def apply(value: String, x: Int): Greeting = Macro.restligeist("0.2.0 apply no longer exists.")

[eed3si9n]

I though it might be useful to express the removal along side the still-alive fields, but I guess it doesn't add much.

[dwijnand]

For instance:

type Greeting {
  value: String!
  sshUsername: String @since("0.2.0") @deprecated("0.3.0", "Use ssh agent instead")
  sshPassword: String @since("0.2.0") @deprecated("0.3.0", "Use ssh agent instead")
  number: Long @since("0.3.0")
}

Generates

object Greeting {
  // 0.0.0
  def apply(value: String): Greeting = new Greeting(value, None, None)

  // 0.2.0
  @deprecated("0.3.0", "Use ssh agent instead")
  def apply(value: String, sshUsername: String, sshPassword: String): Greeting = new Greeting(value, Some(sshUsername), Some(sshPassword), None)

  // 0.3.0
  def apply(value: String, number: Long): Greeting = new Greeting(value, None, None, Some(number))
}

[dwijnand]

lol I always get my "since" and "message" the other way round (until I check).

Should be @deprecated("Use ssh agent instead", "0.3.0").

[eed3si9n]

Maybe we'll use @deprecated("0.3.0", "Use ssh agent instead") ordering in Contraband schema.

[dwijnand]

While I do really prefer that order, personally, let's not (semi) arbitrarily switch the order.

[eed3si9n]

Yea. I was kidding on the ordering. (Although it might be interesting to give warning when we detect flipping.)

[dwijnand]

Indeed. I think I saw commits in scala/scala fixing the same mistake. It's an easy mistake to make when they're both strings..

[som-snytt]

I always write since="1.0". I remember my deprecator plugin included validating that the since at least looked like a version. Note that I never remember message= or msg= so I never write that. OK I checked, it's message= which is too much data entry. A recent crossword clue was "request to a waiter", with the answer, "no msg".