Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: include all removed/renamed/deprecated attribute keys in yaml #214

Open
dyladan opened this issue Jul 26, 2023 · 6 comments
Open
Assignees

Comments

@dyladan
Copy link
Member

dyladan commented Jul 26, 2023

Some (most?) SIGs including JS and Python consume the semconv yaml and generate a semantic convention helper package. When an attribute is renamed, this means the code generator no longer outputs it, resulting in a breaking change for the code generators. Especially now that the spec requires us to double-publish old and new semantic conventions when there is a stabilization effort which breaks semconv, it would be much easier if the generated packages contained deprecated/removed/renamed keys.

My proposal is simply to create a deprecated.yaml file which contains all removed attributes from all versions of the semconv for use by code generators. If a key is renamed, removed, or otherwise excluded from code generation it should be added to deprecated.yaml.

@aabmass
Copy link
Member

aabmass commented Jul 27, 2023

What do you think of adding a deprecated flag for semconv entries? That would make it easier to keep generating them in the same place (code or markdown tables) but add some note they are deprecated.

@Oberon00
Copy link
Member

Oberon00 commented Jul 28, 2023

This flag already exists and can be used.

(I think it would be worth considering adding some more meta-information to be able to generate all schemas from the latest YAML model, but thats off topic a bit, sorry)

@jsuereth
Copy link
Contributor

We discussed this in the SiG. While there are many concerns, I think there's enough interest to more formally flesh out this proposal.

A few things brought up:

  • If we needed to take down an attribute for some extreme reason (e.g. legal?) would this be allowed, and how would it happen.
  • Would we have a "cleanup" process eventually, say every N years? Would this be of benefit?

@dyladan
Copy link
Member Author

dyladan commented Aug 1, 2023

What do you think of adding a deprecated flag for semconv entries? That would make it easier to keep generating them in the same place (code or markdown tables) but add some note they are deprecated.

There is already a deprecated flag in the yaml schema which would be used for this purpose.

We discussed this in the SiG. While there are many concerns, I think there's enough interest to more formally flesh out this proposal.

Can you document the concerns here so I can respond to them?

  • If we needed to take down an attribute for some extreme reason (e.g. legal?) would this be allowed, and how would it happen.

I think this is vanishingly unlikely to happen and the same question can be made of the existing semconv. I think if it ever did happen we would simply delete the attribute and follow the appropriate semver process.

  • Would we have a "cleanup" process eventually, say every N years? Would this be of benefit?

I don't really see a benefit of cleanup. Even if we deprecated hundreds of attributes per sprint it would take a very long time for the file to grow beyond a few megabytes. Having the full history also has the benefit of ensuring we don't accidentally re-create an attribute which shares a name with a previously deprecated attribute which could potentially confuse consumers.

@rapphil
Copy link
Contributor

rapphil commented Sep 15, 2023

For reference, the deprecated semantic attributes live here: https://github.com/open-telemetry/semantic-conventions/tree/main/model/deprecated

@github-actions github-actions bot added the Stale label Feb 16, 2024
@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale Feb 26, 2024
@joaopgrassi joaopgrassi removed the Stale label Feb 26, 2024
@joaopgrassi
Copy link
Member

This was closed by mistake by the stale bot. Re-opening

@joaopgrassi joaopgrassi reopened this Feb 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

7 participants