search

dotnet / roslyn

The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs.
https://docs.microsoft.com/dotnet/csharp/roslyn-sdk/
MIT License
19.06k stars 4.04k forks source link

Decide on rules for WithTrackingName #61888

Open CyrusNajmabadi opened 2 years ago

CyrusNajmabadi commented 2 years ago

As part of a recent API addition for incremental generators, @chsienki raised the point:

We need the tracking names for our internal testing, but they 'leak' into public as they'll now show up in users tracking results if they use this API. I think thats fine, but I think we should get consensus that we're a) ok with that and b) agree that this is not a public API contract and the nodes can be removed / renamed without it being considered a breaking change.

We need to establish what our policy is here, and then document it appropriately for customers.

Personally, i believe all we need to say is that tracking names are purely for debugging/diagnosing/testing purposes, and they are not guaranteed to be stable in any way. Code should not take a dependency on it.

333fred commented 2 years ago

API Review

Conclusion: We should document that tracking names are not considered public API and users cannot depend on them being consistent in generators they don't own.

jaredpar commented 2 years ago

@333fred

We should document that tracking names are not considered public API and users cannot depend on them being consistent in generators they don't own.

Where should we document this though? Is it sufficient to update our document comments or do we envision this happening elsewhere?

333fred commented 2 years ago

Where should we document this though? Is it sufficient to update our document comments or do we envision this happening elsewhere?

Our comments should be sufficient.