Organized deprecations flow

As suggested in https://github.com/serverless/serverless/pull/6195#issuecomment-590249791 (cc @BryanCrotaz) it’ll be nice to incorporate some safe way to introduce breaking changes to framework.

Ideally:

• Any feature to be removed (prior being removed with a new MAJOR), should be announced as breaking with a new MINOR release. (It might be good to require a minimum 2 months period between announcing feature as deprecated and releasing a new major that makes it effective).
• Deprecation notices should displayed for any command, which loads plugins and resolves user configuration. There should be no case where deprecation messages are shown for sls deploy but are not for e.g. sls package or sls info
• Deprecation notices for given feature should be displayed only if user relies on that feature. There should be no case where we pollute log with noisy messages which do not apply to given service.
• New MAJOR should only remove deprecated features. Therefore users which ensured to address all deprecation messages should feel safe to pursue with an upgrade.
• It should be possible to silence all or specific deprecation logs (although single warning should be outputted, notifying it’s the case, and that it might unsafe to upgrade to new major).

As I see there was once an attempt to introduce that (cc @pmuens @eahefnawy) (https://github.com/serverless/serverless/issues/3211) but it was quickly reverted (https://github.com/serverless/serverless/pull/3418), The only outlined reason fo revert was: it harms DX. Still then it was designed to output logs unconditionally, even when user was not in a scope of a service, or was in a scope of service which didn’t rely on given feature. In given case indeed it could have been considered as harmful for DX

Implementation spec proposal

• Introduce logDeprecation(code, message, { serviceConfig }) in lib/utils/logDeprecation.js which should be used to log deprecations. It should be plain function free from attachment to Framework classes (as it might be used before Framework is initialized) with following logic implied:

  • Given deprecation (identified by code) should be logged only once. So if it’s invoked repeatedly with same depracation only first invocation should produce log
  • Internally SLS_DEPRECATION_DISABLE env var should be resolved (possible values: * or {deprecationCode1},{deprecationCode2},...{deprecationCodeN}, and listed depracation codes should not be logged.
  • Same optional serviceConfig should be handled from which we resolve serviceConfig.disabledDeprecations (could be a single value string on array)
  • I propose following look:

• Each deprecation should be documented (possibly in docs/deprecations.md) with a clear resolution instructions. Each deprecation log should link document page and section which provides insight on given deprecation

[medikoo]

In case of this util, I think tests you did are fine, no need to rely on runServerless as util is pretty top level and totally isolated from Serverless class

Concerning tests documentation, we already have document here: https://github.com/serverless/serverless/blob/master/tests/README.md (and it’s linked in: https://github.com/serverless/serverless/blob/master/CONTRIBUTING.md)

runServerless is documented here: https://github.com/serverless/test/blob/master/docs/run-serverless.md but indeed modulesCacheStub documentation is pretty vague.

Anyway feel free to propose any improvements to above. I totally agree that there’s a big room for improvements in docs.

[medikoo]

Should I just import a function module.exports = logDeprecation? Then, I depend on closure variables to keep track of which codes were printed

Yes, I think it should be as simple as possible,

In testing, I need to re-require the module to reset the variables in closure.

When using runServerless util, you can enforce that for each serverless instance modules are re-initialized by passing modulesCacheStub: {}. So I believe that should solve that problem