0.11 Release plan

See original GitHub issue

This is a meta issue to track/discuss what should be done in the next release. The tasks reflect my proposal, any feedback/help is more than welcome!

Parity with opentracing-api from Java

The main thing that’s missing right now is the support for scopes. This will only add new types/members but it will still be a breaking change (for implementations) since it adds members to an existing interface (ITracer).

Apart from that, the C# version currently has some other differences. We want to be as close to the Java version as possible so we will only keep differences that make sense for C#/.NET. We will do this with #50 which basically replaces the whole codebase and is based on the current master of opentracing-java.

This PR will introduce the following changes to the current code:

Log methods will use IDictionary instead of IEnumerable. There’s a discussion in #44 about whether or not there should be other changes regarding this in a later version.
We will remove the FollowsFrom() methods in ISpanBuilder as they currently don’t exist in Java.
We will use Java’s Tag types instead of our simple Tags-type with constants.
We will use Java’s propagation types. Our types were slightly different.
~~We will add support for the BINARY format. It will be based on Stream~~
- ~~I still don’t know if that’s correct since I don’t understand how this format is used - see also #7.~~
- Edit: we decided not to add BINARY for now as there’s also some discussion around it in Java.
We will remove the NullTracer from the core API. We will follow Java’s lead and add it as a NoopTracer to a different package.
- The current implementation is not good as there’s currently a namespace and a type called NullTracer so one has to write NullTracer.NullTracer.
We will remove our exception types (OpenTracingException, UnsupportedFormatException) as they don’t exist in Java (they were from an unmerged PR)

Changing these things obviously results in a ton of breaking changes but I guess the impact is still minimal and the benefit of being on par with Java outweighs it.

We will keep the following differences. Please comment if you want to remove any of these differences as well!

We are using DateTimeOffset instead ticks for tracking timestamps. The reasons for this are described in #4 and #42.
We have a OpenTracing.LogFields type and Java has a OpenTracing.Log.Fields type, so the namespace and type names are different.
- I think that makes a lot more sense as it doesn’t introduce a new namespace for one file. Also, the Log-method is in the “OpenTracing” namespace so there’s no point in having the constants in a different namespace.

Tasks:

Merge #50
Remove exception types #64

Enhancements / Additions

We don’t yet have an equivalent for Java’s additional packages “util”, “mock” and “noop”. We will implement all of these in one OpenTracing.Utils package to reduce the number of packages.

Please comment if you want to have separate libraries!

Tasks:

Implement a GlobalTracer (#45, #61).
Implement the necessary types for scopes. They will be different though as .NET has AsyncLocal. (#63)
Implement a MockTracer (#54).
Implement a NoopTracer (#57).

Making sure stuff works

We only have a few unit tests as most of the code is interfaces. However we definitely need to port the tests from Java’s util-package and we need to write our own for our AsyncLocal implementation.

We should also confirm that the API can actually be used by using it somewhere. I don’t know if the basictracer-packages are still used in other languages. If so, we should update basictracer-csharp. Otherwise I have some personal prototypes. Other projects that would be willing to test stuff would be appreciated.

Tasks:

Add unit tests for Utils
Verify API usability in a project (e.g. basictracer-csharp)

Infrastructure

People targeting the full framework currently get a lot of dependencies due to NETStandard.Library. We should either move to “netstandard10;net45” or even better “netstandard20;net45” (#51, #56, #62).
The build no longer works for me with 2.* SDKs of .NET core since some CLI commands have changed. (#56)

Schedule

I’ve got some time next week, so I’d like to have PRs and discussions for the core API as far as possible by the end of next week. I can also create the utils-project with implementations for GlobalTracer and scopes. So depending on your feedback and the timeframe of other people who want to contribute, we might want to target a release between 02/15 and 02/28?!