Add deprecation warnings for user-defined members

[tay1orjones]

Could @warn be updated to emit a warning message when variables are used?

For the Carbon Design System we use Sass for all the styling we provide to users. We're in a situation where we have a lot of variables that are going to be removed in our next major. We'd like to provide deprecation warnings to developers when these variables are used, but unfortunately the @warn rule is scoped to only functions and mixins.

Apologies if there's already another issue that encapsulates this idea more fully, I couldn't find one though.

[tay1orjones]

One way around this would be to allow users to opt-in to the removal by placing these variables behind a legacyTokens feature flag and conditionally emit them if the flag is true. In our next major, make this flag false by default.

This doesn't help us provide early warnings though like @warn would. Are there some other alternatives to consider?

[nex3]

This is an interesting question. Your use-case is compelling; it's definitely a good idea for library authors to have a way to deprecate variables. I can see two broad avenues for supporting this:

1. Add a dedicated syntax for it. You could imagine $var: value !deprecated, although that doesn't provide much information to the user about why the variable was deprecated or what should be used instead. We could make the syntax more complex in one direction or another to accommodate a customizable deprecation message.

2. Add a way to define something like JS properties, where a value can be accessed (or modified?) using variable syntax but in actual fact runs a function to produce its actual value. This would give authors the flexibility to add a @warn to the variable's value, but it would also provide a lot of additional power—as well as a lot of additional language complexity.

I'm not sure there's a lot of value in option 2 outside of this, so I'm leaning towards option 1, but I don't have a great syntax in mind for it that supports a customizable message.

[tay1orjones]

Yeah, I agree a deprecation warning without a custom message instructing users how to fix the warning would be less than ideal. Option 1 would meet our use-case well enough though with the ability to provide that custom message.

In our case, we're already using sassdoc @deprecated annotations to note deprecations with a message, but of course this is only present in the docs generated from sassdoc and does nothing to help notify developers in their project/coding environment. Maybe there's an opportunity to lift up those messages and surface them through the sass runtime itself when encountering a !deprecated flag?

[nex3]

Canonizing SassDoc comments is a very interesting concept here. We wouldn't want to do that for anything semantic, but if it's just for a deprecation warning I think we could probably get away with it.

Another option could be to have a separate rule like @deprecate $variable "message" but the SassDoc option might be cleaner. We could potentially even do away with the !deprecated flag entirely and just define special messaging behavior for any module member with a @deprecated comment.

We'd probably also need to find a way to suppress warning within the same package. If the $color variable is deprecated, you don't want to surface deprecation warnings when your own library checks if it's been set or not. We could probably re-use the existing "silence upstream packages" logic to say that "anything that's transitively connected by a relative-path load is in the same package"....

[tay1orjones]

Canonizing SassDoc could have another side benefit on our end of not having to update any of our code. We, and consumers of our libraries, would update to the latest sass version and automatically get deprecation warnings across all previous versions of our library (that used the SassDoc @deprecated) even from releases years ago.

[nex3]

Yeah, I think that's probably the best way forward.