Proposal: deprecation

[romshark]

This is a language feature proposal to enable deprecation for graph nodes, types & transactions to allow for gradual API evolution.

struct Struct {
  field String
}

transact Transaction(arg T)

# Struct.field will be removed in the upcoming version v2.0.0, use ... instead
deprecation Struct.field v2

# Struct will be removed in the upcoming version v3.0.0, use ... instead
deprecation Struct v3

# Argument arg of transaction Transaction will be removed in the upcoming version v2.0.0
# use ... instead
deprecation Transaction.arg v2

# Transaction will be removed in the upcoming version v2.0.0, use ... instead
deprecation Transaction v3

deprecation marks a symbol deprecated until the given major version vX (according to semver). A deprecation can be documented to denote alternatives for example. Note that nodes cannot be deprecated targeting versions after the deprecation target version of their parent.

When releasing a new version of the schema all deperecations targeted at it must be removed.

NOTE: It's not yet clear however how to deprecate transaction nodes (return values).

[romshark]

According to the recent changes (#12) the above examples would now be:

struct Example::Struct

# Struct will be removed in version v3.0.0
deprecated v3

properties {
  field String
}

deprecations {
  # field will be removed in version v2.0.0
  this.field v2
}

or

transact Example::Transaction

# Transactions will be removed in version 3.0.0
deprecated v3

arguments {
  $arg T
}

deprecations {
  # $arg will be removed in version 2.0.0
  this.$arg v2
}