Initial cut at laying out core principles for Specification change.

[jsuereth]

Fixes #4276

Changes

Documents the values we use when evaluating specification changes. Also sort out the specification README to clarify which components cover Principles and Values.

• These values can be at odds with each other.
• These values require subjective judgement.
• These values can and should be understood and backed by the whole community.

• CHANGELOG.md file updated for non-trivial changes
• spec-compliance-matrix.md updated if necessary

[reyang]

LGTM with some minor suggestions.

[pellared]

1 minute review, will do better once I find some time.

[tigrannajaryan]

All LGTM, except one sub-principle which I think can be misinterpreted, see the comment.

[jack-berg]

I don't disagree with anything in here, but wish there was some way to give more practical advice on a few topics I see coming up a lot:

• Should we extend an interface, even when its allowed? Extending interfaces is easier in some languages than others. Ideally we get it right the first time (and we should strive for this), but in the event we don't, when does the value of extending an interface trump the friction it causes in the languages where they are hard to extend? This is related the "be stable" value, but not entirely captured.
• Language implementation or collector. We often have proposals for use cases that could be done in the collector, but could also be done in the SDK which is advantageous to some users who don't want to use the collector (or in some cases can't). Given that spec API / SDK features need to implemented 11 times, when is it appropriate to reject a API / SDK feature proposal that can be accomplished in the collector? Doing so can help us focus on more pressing problems, and potentially simplify user story by reducing the number of ways to accomplish the same thing.
• Plugin extension point or structured config. There’s a trade off between SDK plugin extension points (i.e. exporters, processors, samplers), and a more limited or structured approach (i.e. exemplar filters, attribute limits). SDK plugin extension points offer more flexibility but generally have more cumbersome and less standardized configuration. Reducing flexibility (or adding guardrails) can add safety and improve UX in certain domains. When do we choose one or the other? This is related to the "be simple".

It could be the case that we don't have enough experience yet to extract out useful principles on these, but these are the types of questions I see recurring.

Approving because while I think there's even more we could offer contributors, I agree with what is written here.

[jsuereth]

@jack-berg I think maybe your specific things can be "examples" or "faq" section. I've been thinking about this comment (and @tigrannajaryan's) for a bit, I'm going to give this an update to account for that, will notify when it's complete.

Agree we should address common concerns and show the interplay of these principles.

[carlosalberto]

As we have enough approvals, one option is to address the important points raised by @jack-berg as a follow up.

[jsuereth]

@carlosalberto That sounds like a plan, it's going to be a new section anyway. I'll address @tigrannajaryan's comments and we can follow up with @jack-berg's in a future PR

[jsuereth]

I don't disagree with anything in here, but wish there was some way to give more practical advice on a few topics I see coming up a lot:

• Should we extend an interface, even when its allowed? Extending interfaces is easier in some languages than others. Ideally we get it right the first time (and we should strive for this), but in the event we don't, when does the value of extending an interface trump the friction it causes in the languages where they are hard to extend? This is related the "be stable" value, but not entirely captured.
• Language implementation or collector. We often have proposals for use cases that could be done in the collector, but could also be done in the SDK which is advantageous to some users who don't want to use the collector (or in some cases can't). Given that spec API / SDK features need to implemented 11 times, when is it appropriate to reject a API / SDK feature proposal that can be accomplished in the collector? Doing so can help us focus on more pressing problems, and potentially simplify user story by reducing the number of ways to accomplish the same thing.
• Plugin extension point or structured config. There’s a trade off between SDK plugin extension points (i.e. exporters, processors, samplers), and a more limited or structured approach (i.e. exemplar filters, attribute limits). SDK plugin extension points offer more flexibility but generally have more cumbersome and less standardized configuration. Reducing flexibility (or adding guardrails) can add safety and improve UX in certain domains. When do we choose one or the other? This is related to the "be simple".

It could be the case that we don't have enough experience yet to extract out useful principles on these, but these are the types of questions I see recurring.

Approving because while I think there's even more we could offer contributors, I agree with what is written here.

Opened #4293 to address

[cijothomas]

Left a minor comment, not a blocker!
Very glad to see this written down.