search

blackducksoftware / hub-client-go

Hub Client for Go (golang)
Apache License 2.0
9 stars 19 forks source link

Change methods that accept a hubapi.ResourceLink to accept a string instead #54

Open brekelj1 opened 4 years ago

brekelj1 commented 4 years ago

I have a use-case where I have a string that is the URL to pass to ListProjectVersionComponents. But the function ListProjectVersionComponents requires a ResourceLink object, and it only uses the Href field.

It is better to change API-call functions that only use the Href field of a parameter of type ResourceLink to accept a string instead.

Existing callers that rely on a ResourceLink type of parameters can easily add a .Href to their code when upgrading to the new client.

tandr commented 4 years ago

There is a surprising amount of code that uses this library. I don't think it is a good idea suddenly to change publicly available API, and (preferably) we need to be consistent. As such, it can go multiple ways

  1. Do nothing. Yes, it is annoying. Yes, it is inconsistent. But - "historical reasons".
  2. Or just change that one function and pray not many people used it.
  3. Or go and do it for every place where ResourceLink is used. Preferable mark it with // Depricated, create a parallel set of API so people can migrate to it.
  4. Or do exactly opposite, and use ResourceLink everywhere. Check and mark all places that ResourceLink should be used as // Deprecated:, create a set of new calls so people can migrate to new API as they see fit.

In case of 3 and 4 old API can stay forever actually, it does not hurt too much to have a small wrapper that redirects to "new and shiny".

In any of these cases -- someone should do it. If you feel strongly about it -- MRs are welcome, but please don't forget about other developers.

brekelj1 commented 4 years ago

Thanks for your prompt reply. I would like to share an alternative: using versioned go modules so that backwards compatible changes can be made, as follows: For each major release create a branch (i.e. release/v1 from which tags v1.x are created). Users can then download go-module/versioned version of this package.

The penalty is that bugfixes have to be applied for each such branch, so we should plan carefully and batch changes that are backwards incompatible to limit the maintenance introduced. New endpoints only have to be added to the latest release branch. I suspect the extra maintenance will be very low since I doubt there are many bugs in the API client code, so really there is little disadvantage to this approach.

@tandr what do you think about this?

tandr commented 4 years ago

Or just use go.mod and versioning associated with this. Using versioned directories with copies of the code is nightmare to maintain, I would prefer not to go this direction.

There are couple things to consider

  1. This means we will have to declare go 1.14 as minimum. (yes, modules are available to earlier versions of Go, but I don't think they worked all that great before 1.14, and nobody has time to troubleshoot it.)
  2. Not every project uses modules yet. Maybe it is time to switch to it, but as it stands, there are people who cannot use it for whatever reasons.
  3. All of above still means we need compatibility.

That said -- you can provide (patch) additional functions that use straight string as params, and if you prep the patch, we can review it here.