Adds Experimental Attributes

[NeedleInAJayStack]

This generates and exposes unstable attributes like those marked development, experimental or release_candidate, and gates them behind a non-default Experimental trait.

closes #27

[NeedleInAJayStack]

I created the experimental trait as discussed in #27, but what do you think about using "Unstable" instead?

[slashmo]

Thanks, I'll get to a detailed review later. One thing I thought about is that just having the trait without additional markers on the unstable attributes may be a bit too little because you don't immediately see whether you'd even need the trait based on the attributes used. One option I thought about is to prefix them all with experimental/unstable, so it's immediately obvious from the call-side. What do you think?

[czechboy0]

I like that. Plus we should add a clear note in the Readme explaining that if you use the experimental trait, you must use .upToNextMinor as they might break between minor versions.

[NeedleInAJayStack]

Yeah, definitely a good concern. The only thing I'd want to be careful of is to abide by the Development section of the stability guide, in particular:

OpenTelemetry clients MUST NOT be designed in a manner that breaks existing users when a signal transitions from Development to Stable. This would punish users of the release candidate, and hinder adoption.

I believe that this would disallow any symbol-prefixing or namespacing (since abc becoming stable would transition the symbol from experimentalAbc -> abc, and break existing users).

Two approaches that come to mind and are compatible with the spec:

1. Using @available attributes to provide compiler warnings on non-stable attributes. This may be too intrusive, as some projects consider any compiler warnings to be a code smell.
2. Adjusting documentation to more obviously flag non-stable attributes as mentioned in the issue. This may not be intrusive enough, as a user might not view the docs before using.

What do you guys think?

[czechboy0]

Maybe doc comments are enough, combined with the package trait.

[slashmo]

Ah, thanks for linking to the spec. I agree that it makes sense to follow it here. As you suggested option 1 with @available checks seems too intrusive because it would basically "punish" users of the unstable API always, not just when upgrading to a release that graduated some of the unstable attributes.

So overall I agree that the best option is to make it very clear in the documentation of individual attributes and in the trait documentation.

[NeedleInAJayStack]

Sounds good! I've added a big, bolded **UNSTABLE** to the beginning of each attribute documentation here: aadf494

[czechboy0]

Let's add an explicit instruction to use .upToNextMinor, so that at least we promise not to break them between patch versions.

[NeedleInAJayStack]

Good thought - I was going to do that, but it looks like .upToNextMinor is deprecated, so I went with explaining the equivalent range restriction. Is that right that it's deprecated?

[czechboy0]

I think this is the right one, on Range, not deprecated https://developer.apple.com/documentation/swift/range/uptonextminor(from:)

[NeedleInAJayStack]

Oh awesome, thanks for linking that! I've adjusted the documentation in 30eb17f to recommend that upToNextMinor is used.

[NeedleInAJayStack]

I also changed name of the "Experimental" trait to "Unstable" in c8b909c, since it slightly more accurately describes which attributes are included. Let me know if you disagree.

Edit: This has been reverted to "Experimental" based on the discussion here: #43 (comment)