Giters

doccano / doccano-client

A simple client for doccano API.

Home Page:https://doccano.github.io/doccano-client/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Integrating Our Version of doccano-client?

ljades opened this issue · comments

commented

Feature description

Hey y'all,

First of all I just wanna say: Great job on this client!

Our company actually has been working on and maintaining a doccano-client as well around the time progress on this client started. It's currently internal, but we could easily open source it--hardly any of it is opinionated to our company's use cases.

The problem is, we don't have the hands at the moment to consistently maintain the package and keep it up to date with all the updates Doccano receives. It looks like this package has been able to, however, thanks to the open source visibility!

An idea: What are ya'll's thoughts on uniting the two? We can move our code to a fork of this repo, and create a major PR that integrates it right into this package if you like the results!

We believe our version of the client has a lot of features that this one can greatly benefit from:

  1. Versioning lines up with Doccano release tags, so it is always clear when it will be compatible with which release of Doccano's API.
  2. All interactions with the API are pythonic, rather than based on raw json. Example below.
  3. VERY heavily unit tested.
  4. Black, Isort, Flake8, Pydocstyle, Pylint, and Mypy compliant
project_controllers = client.projects.all()

my_project_name_controller = next(controller for controller in project_controllers if controller.project.name == "My Project Name")

my_project_name_controller.labels.update([Label(...), Label(...)])

test_example = models.Example(text="This is an example text")
my_project_name_controller.examples.create(test_example)

Would you be interested in this style? There are a few more layers so may take a bit more code to maintain in some ways, but it should cut a lot of tech debt, making it easier to scale. If you're interested, we can port our code to a fork of this repo so you can take a look.

Thank you for your time!

commented

@Hironsan Hey thank you so much for the quick response on this and the merge!

But now I'm curious for how you recommend we move forward with contributing to this. Can you answer these questions for me?

  1. The primary client functionality is updated to compatibility with Doccano v1.6.x, correct? The new stuff we just merged is compatible with Doccano v.1.5.x. I set the new versioning in the setup.py to match our internal version, at 1.5.1. What do you think the version should be set to--should it match the new beta code or the main code interface? Or should we align them first, then set the version? Personally, I'm veering towards keeping it in the 1.5.x range until doccano-client is released at least once in that range (maybe set it to 1.5.5 at release to match the last stable Doccano release). Then we can switch to 1.6.x versioning here as well.
  2. Should we add pytest to CI checking? My team can integrate that if it makes sense.
  3. Once we have pytest verified as passing, when can we expect a release on this? If my team can start using this package once we confirm it's reasonably stable, we can stop using our internal package entirely and start contributing to this one directly instead.

Thanks!

commented

Your welcome. Thank you for your great work!

  1. The primary client functionality is updated to compatibility with Doccano v1.6.x, correct?

Yes.

I think we can replace the current code with the beta code after supporting v1.6.x compatibility. The new code is great.
In this case, the version of doccano-client will be v2.0.0 (the current version is v1.0.3) because there are incompatible API changes.

  1. Yes!
  2. Choices are:
  • v1.1.0(the current code and the beta code). In this case, I can release the package soon.
  • v2.0.0(only the beta code with v1.6.x compatibility)
commented

I think we can replace the current code with the beta code after supporting v1.6.x compatibility. The new code is great.

Oh wow that'd be a major stride and extremely humbling :)

  1. Awesome! We'll get some cycles on this very soon. Probably in the next week or two--we're also gonna try to make the connection to the beta. Afterwards I think we'll be good to release this.
  2. Re:the semver stuff from earlier too, yeah I hear what you're saying regarding fundamental API changes. The goal overall though with the versioning is that the Major and Minor version should have parity with Doccano release numbers, right?

What would you suggest would be the cleanest strategy to both follow good semver practices and also try to align with Doccano releases eventually too?

One idea would be to have them independent until Doccano is at 2.0.0, THEN bring this to 2.0.0 and leave only the beta code. That might be a while though.

Another option may be to have the next few versions of doccano-client bump minor version one-by-one (so 1.1.0, 1.2.0...1.6.0, until it matches Doccano's 1.6, then bring it back to Patch version bumping after).

Any other ideas?

commented

I do not think it is necessary to align the doccano and doccano-client versions. This is because increasing the version of doccano does not necessarily cause changes in the API(e.g. patch version update by some bug fixes). In my opinion, the doccano and doccano-client versions should be independent. It is hard to align them.

I have checked several project versions:

One idea would be to have them independent until Doccano is at 2.0.0, THEN bring this to 2.0.0 and leave only the beta code. That might be a while though.

Yes. You are right. It may take a long time.

Best

commented

Gotcha. What do you think is another way we can clearly define API compatibility, in that case?

For example, should we add it to the changelog instead, and just rely on that + the comment block in the setup.py?

I am content with them being independent as long as we are defining that clearly. So that, for example, someone using Doccano 1.5.x knows not to upgrade their doccano-client version to a certain new version if it's optimized for a new API structure.

commented

Writing the compatibility to the documentation and comment is good.
In another way, how about letting the user specify the version? For example:

client = build_client(version="1.5", endpoint="http://")
client.login()

This is an analogy of google-api-python-client.

However, it might be troublesome to specify the version.

commented

Yeah that'd probably be more challenging. Would involve supporting multiple versions of the Doccano API at once in possibly quite a lot of long-term permutations.

Anyway, thanks for the recommendations! We're gonna make one or two more PRs (the pytest CI inclusion, a bit more intuitive tie-in of the beta stuff into the existing documentation/module importing) and then I think we should be good for a release!

commented

Thanks! I will make time and review it.