Implement a standard pattern for deprecating features

[ThomasLaPiana]

Is your feature request related to a specific problem?

As we continue to refine and iterate on fidesctl, we're increasingly going back and wanting to make breaking changes. To follow best practices and not give our users unpleasant surprises, we should be following a standard "deprecation path" any time we want to get rid of an older feature.

Describe the solution you'd like

That's what this issue is going to discuss!

[sanders41]

I commonly see warnings used for this. Some examples:

1. Flask - https://github.com/pallets/flask/blob/095651be9eec58ddb0c2eb6158318b1c703c67c5/src/flask/init.py#L53
2. Pandas - https://github.com/pandas-dev/pandas/blob/9a2276fddc2e72b74a8bba1d50c862b3fb5a176c/pandas/init.py#L200

[NevilleS]

Based on some of our team discussions around this, what we've proposed thus far is:

1. Flag any breaking change by first marking the feature as deprecated for at least one release cycle
2. Raise FutureWarning exceptions for this, and catch these with top-level handlers in the CLI/API that then output clear WARN logs like: WARNING: 'deprecated_command' is deprecated, and will be removed in the next major version of fidesctl. In the future, use 'command' instead.
3. For CLI commands, render the log message immediately to stdout so the user can see it
4. For API calls, output the log to the logger where we hope the user will review it
5. List all deprecations/breaking changes in the Changelog prominently
6. Adopt "true" semver semantics for breaking changes once we surpass 2.0.0

Also worth mentioning a few examples of the types of breaking changes we are likely to want to make:

• Renamed API route (e.g. /api/v1/foo -> /api/v1/bar)
• Renamed config variable (e.g. FIDESCTL__FOO -> FIDESCTL__BAR)
• Removed CLI command (e.g. fidesctl foo is removed)
• Removed UI feature (e.g. /admin/systems/foo is no longer supported)

In most of these cases, I do think that outputting warnings to the CLI & logs will probably work, but I would also love if the server could maintain a small amount of state for "recently used deprecated feature warnings" and return a list of warnings in the /health endpoint (or similar) so that we could also show warnings in the admin UI. This would help a lot for notifying users about deprecations if they aren't watching the logs carefully.

[ThomasLaPiana]

@mfbrown I think this is worth getting on the board in sprint 5? to at least lay the pattern down, I foresee us needing to leverage it more and more in the near future