Suppressing deprecation warnings abuses element/source overrides

This is an API inconsistency I think is worth fixing.

Essentially, what is happening here is that we are hijacking the elements: / sources: dictionaries which exist to uniformly override plugin default configurations, and adding an additional key which is not even a part of element/source declaration YAML.

Negative side effects of this include:

  • Opening up a slippery slope of this continuing to happen, providing an overall inconsistent API story
  • Possibilities of keys snuck into the overrides namspace clashing with actual declaration YAML
  • Inconsistent API documentation story.

I think the last point here is the worst, for every single key in the BuildStream YAML format, we have a piece of documentation which specifically describes it, every key has it's own section and is fairly well categorized in the reference manual; this also allows for standard expressions like "This key was added since version 2.2" and such.

Instead in this case, we have a mere mention in the plugin.py documentation saying:

This deprecation warning may be suppressed on a plugin by plugin basis by setting suppress-deprecation-warnings: true in the relevant section of the project's plugin configuration overrides.

Proposed fix 1

The most sensible thing here is to have this configuration in the declarations of plugins a project uses.

Here is one normally declares which plugins the project is going to use, so it is a natural place to have the configuration of whether to care about deprecation or not. It is also tied directly to the plugin loading code which is a natural place to raise such errors.

Proposed fix 2

The suppress-deprecation-warnings needs to become a first class key on elements and sources, even if this means that the warnings can be suppressed on one plugin instance, this would not be a breaking change because we could continue overriding the valid key in the overrides.

I like this solution less but if we really want this to be set in the overrides, it really should be valid plugin declaration YAML.