Update documentation around deprecation policy

[not-an-aardvark]

In #5845, we discussed the tradeoffs of removing rules versus deprecating them. Removing rules causes a lot of pain for users since they need to update their configs, and arguably there is not much benefit in removing rules rather than deprecating them. We decided to adopt the following policy through May 1st, 2017, and then reevaluate afterwards:

• Don't remove any rules
• Don't accept any changes to deprecated rules

That date has passed, so now that the year-long experiment is over, we should make a decision about how we will handle rule deprecations in the future.

---

Personally, I've found that deprecated rules impose a very low maintenance burden. Since we don't accept changes to them, I generally don't need to worry about them at all when developing.

The one exception is that when I enable new lint rules on the codebase, I sometimes have to manually make changes to the deprecated rules to allow them to conform to the new lint rules. This can take a nontrivial amount of time. However, we don't enable new lint rules very often, so I don't think this poses a significant maintenance burden compared to other everyday tasks.

So my opinion is that this experiment has gone well, and we should continue to never remove rules or accept changes of deprecated rules indefinitely. I'm interested in hearing other peoples' thoughts on this.

[not-an-aardvark]

cc @eslint/eslint-team

[ilyavolodin]

I'm as split on this now as I was when we originally discussed this issue a year ago. I really like deleting code, but I see the value in keeping deprecated rules around.

[platinumazure]

I have one question: What should happen if a deprecated rule's replacement, itself becomes deprecated and replaced by an even better rule?

Is there any chance that could cause confusion? Should we consider adopting a practice of ensuring the oldest deprecated rule points to the newest rule rather than its immediate replacement, and if so, would the maintenance burden of that potentially be unacceptable?

Otherwise, I'm with @ilyavolodin-- it would be great to delete code at some point (and I still like the idea of imposing a long deprecation period before deletion), but there is value in keeping rules around at this point.

[not-an-aardvark]

Is there any chance that could cause confusion? Should we consider adopting a practice of ensuring the oldest deprecated rule points to the newest rule rather than its immediate replacement, and if so, would the maintenance burden of that potentially be unacceptable?

I don't think this would be a big maintenance burden. It seems like we could actually do this automatically.

I really like deleting code, but I see the value in keeping deprecated rules around.

I do too, but I'm just not sure it's worth getting rid of rules when the pose almost no maintenance burden.

It's worth noting that many rules work perfectly fine for users without maintenance, even when deprecated. I think it would be good to be able to say "you can keep using this rule indefinitely" even after we deprecate a rule.

[kaicataldo]

I think it would be good to be able to say "you can keep using this rule indefinitely" even after we deprecate a rule.

I'm on board with this as long as we keep the caveat that deprecated rules are essentially frozen and won't be maintained (we can point users to the replacement rule when issues come up). In doing this for a year now, deprecated rules haven't seemed like they have a notable maintenance cost for the team and reduces the burden of updating configs for users.

[not-an-aardvark]

TSC Summary: A year ago, we decided to temporarily adopt a deprecation policy where we would commit to never removing deprecated rules, and we would also not maintain the deprecated rules. The trial period for that experiment has expired, so we should decide on a deprecation policy going forward.

TSC Question: Should we continue with this deprecation policy?

[alberto]

Given it doesn't cause a maintenance burden and the strong opinion of @nzakas against doing anything differently, I'm in favor of keeping this policy, at least for another year.

[alberto]

Regarding conformance to new eslint rules, I think we could put /* eslint-disable */ in deprecated rules, since they are not maintained anymore.

[not-an-aardvark]

As a follow-up question: Would our "no removing rules" policy also apply to backwards-incompatible schema changes (where a previously-valid schema becomes invalid)? It seems like those would cause a similar problem for users.

[nzakas]

Yes, rule schemes changes should always be backwards compatible. You can always add a completely new scheme in addition to the old, but I don't think we can ever remove an old one.

[btmills]

In the 2017-07-20 TSC meeting, we agreed that the current policy is working well. We will continue to preserve deprecated rules but will not maintain them. In order to close this issue, we need to update the documentation in http://eslint.org/docs/user-guide/rule-deprecation and http://eslint.org/docs/rules/#deprecated to say that we will keep deprecated rules and emphasize that they are not maintained once deprecated.

Regarding #8635 (comment), we agreed that this means we should not make breaking changes to rule schemas.