search

watson-developer-cloud / dotnet-standard-sdk

:new::new::new:.NET Standard library to access Watson Services.
https://www.nuget.org/profiles/ibm-watson
Apache License 2.0
148 stars 117 forks source link

Refactor SDK to accept generated services #103

Closed mediumTaj closed 7 years ago

mediumTaj commented 7 years ago

Currently each service abstraction version shares a readme, unit and integration tests and example project. In the generated SDK I have created service abstractions per version with unit and integration tests and example project per version. https://github.com/mediumTaj/dotnet-standard-sdk-generated

This allows us to have packages for different service versions that have tests, examples and documentation specific to that service version.

The current SDK needs to be refactored such that we can package this way.

Namespaces should change from

IBM.WatsonDeveloperCloud.VisualRecognition.v3
IBM.WatsonDeveloperCloud.VisualRecognition.Example
IBM.WatsonDeveloperCloud.VisualRecognition.UnitTests
IBM.WatsonDeveloperCloud.VisualRecognition.IntegrationTests

to

IBM.WatsonDeveloperCloud.VisualRecognition.v3
IBM.WatsonDeveloperCloud.VisualRecognition.v3.Example
IBM.WatsonDeveloperCloud.VisualRecognition.v3.UnitTests
IBM.WatsonDeveloperCloud.VisualRecognition.v3.IntegrationTests

Directories for Services should change from


IBM.WatsonDeveloperCloud.VisualRecognition

to


IBM.WatsonDeveloperCloud.VisualRecognition.v3

Directories for Tests should change from

IBM.WatsonDeveloperCloud.VisualRecognition.IntegrationTests
IBM.WatsonDeveloperCloud.VisualRecognition.UnitTests

to 

IBM.WatsonDeveloperCloud.VisualRecognition.v3.IntegrationTests
IBM.WatsonDeveloperCloud.VisualRecognition.v3.UnitTests

Directories for Examples should change from 


IBM.WatsonDeveloperCloud.VisualRecognition.Example

to


IBM.WatsonDeveloperCloud.VisualRecognition.v3.Example

To differentiate from different service versions, the Nuget package should change from


IBM.WatsonDeveloperCloud.VisualRecognition

to


IBM.WatsonDeveloperCloud.VisualRecognition.v3
mediumTaj commented 7 years ago

@atilatosta what do you think of this? We need to tie the tests, examples, and readme to the specific service version. Also we can have different nuget packages for each version. Am I not considering something here? I want to start adding some of the generated services to the SDK soon.

atilatosta commented 7 years ago

@mediumTaj I like this way of separation. It makes sense to separate projects by version

mediumTaj commented 7 years ago

@atilatosta OK Awesome! I'll start work on that tomorrow.

mediumTaj commented 7 years ago

@germanattanasio brought up a good point. If an application already is using a package, Visual Recognition V1, for example. Is it an issue to refactor the project to use the the Visual Recognition V2 package to use V2 features? Or is it easier to have a IBM.WatsonDeveloperCloud.VisualRecognition pacakge that just gets updated when V2 is released?

Google has versioned services https://github.com/google/google-api-dotnet-client/tree/master/Src/Generated

Amazon doesn't https://github.com/aws/aws-sdk-net/tree/master/sdk/src/Services

Microsoft doesn't https://github.com/Azure/azure-sdk-for-net/tree/psSdkJson6/src/SDKs

@atilatosta what do you think?

Do we want to remove the version from the namespace and have

IBM.WatsonDeveloperCloud.VisualRecognition IBM.WatsonDeveloperCloud.VisualRecognition.Examples IBM.WatsonDeveloperCloud.VisualRecognition.UnitTests IBM.WatsonDeveloperCloud.VisualRecognition.IntegrationTests

My reasoning for having

IBM.WatsonDeveloperCloud.VisualRecognition.v1 IBM.WatsonDeveloperCloud.VisualRecognition.v1.Examples IBM.WatsonDeveloperCloud.VisualRecognition.v1.UnitTests IBM.WatsonDeveloperCloud.VisualRecognition.v1.IntegrationTests

IBM.WatsonDeveloperCloud.VisualRecognition.v2 IBM.WatsonDeveloperCloud.VisualRecognition.v2.Examples IBM.WatsonDeveloperCloud.VisualRecognition.v2.UnitTests IBM.WatsonDeveloperCloud.VisualRecognition.v2.IntegrationTests

is if there is a case when both versions of the service were live, we would be able to use both. I'm sure this wouldn't be very common.

What do you think? I'd like to get this right before I merge in my generated stuff ;)

atilatosta commented 7 years ago

@mediumTaj I think a good point, but how would users have control over which version are you using?

mediumTaj commented 7 years ago

@atilatosta They would use the particular version of the SDK that supports that version. I think I like separating the services by version though. I feel like service will differ greatly between versions, developers will have to refactor anyway. If the versions are very close, they will just have to change the using statement.