Clarify that Setter sets values only.

[carlosalberto]

Clarify that Setter only sets values - that is, it does not adds values to existing ones.

Related to #444 which aims to (potentially) add an additional Add operation (to added, if needed, after GA).

[Oberon00]

I would like to see some guidance here specifically for HTTP headers. Say,we have multiple headers with name "Foo" in the request (= carrier) and the propagator calls Set(carrier, "Foo", "bar"). Would that remove all the previous Foo headers and then add that single new one with value "bar"?

[carlosalberto]

Would that remove all the previous Foo headers and then add that single new one with value "bar"?

Yes, that's all that a Setter will do at this moment. During our last triage call it was mentioned a Setter is expected to set and override values. This can be explicitly stated in this PR if needed, but if you think we need something else is needed (guidance here specifically for HTTP headers), let's do that in a follow-up PR.

[carlosalberto]

@Oberon00 Applied your feedback using slightly different wording. Please review ;)

[carlosalberto]

@open-telemetry/specs-approvers Please review this. This is a (hopefully) simple clarification on the Setter functionality ;)

[carlosalberto]

@arminru Feedback applied, please review.

[Oberon00]

Actually I am confused by this spec: Does this heading describe the arguments to the setter? Should this be heading be replaced by the sentence: "Inject should have the following parameters:"?

[Oberon00]

I think we went too often back and forth on this PR and now it does not fulfill the originial intent of specifying that values are overriden/only one value per key is supposed to be retained.

I think the PR is still an improvement, so my approval holds, but are you sure this is what you want @carlosalberto ? I would recommend adding some explicit wording what should happen when the setter is called with the same key multiple times or with a key that is already in the carrier (or is in the carrier multiple times even).

[carlosalberto]

To be honest, I'd like to act as @iNikem acted in the past, to avoid scope creep: this PR is doing something and if something else needs to happen, please do that in a follow up. The intention of this PR was simply to avoid using the words "add" and "remove" and use "set" instead.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[arminru]

While this PR does not resolve all inconsistencies in this spec, I still think it's an improvement and should be uncontroversial enough to merge if any other @open-telemetry/specs-approvers would take a look.

[carlosalberto]

Merging as this is merely an editorial clean up.