search

airr-community / airr-standards

AIRR Community Data Standards
https://docs.airr-community.org
Creative Commons Attribution 4.0 International
35 stars 23 forks source link

ADC API versions are confusing, and not right for AIRR v1.4.1 and v1.5.0 releases #760

Closed schristley closed 4 months ago

schristley commented 4 months ago

With AIRR v1.4.1, the OpenAPI 3 spec for ADC API was added, but the versions were not updated.

With AIRR v1.5.0, the ADC API versions were updated and in sync but it didn't skip for AIRR v1.4.1

schristley commented 4 months ago

I would like to make two suggestions.

One, the ADC API already moves on its own version track, so let's create tags like adc-v1.2.0 which explicitly tag the API. This allows the API to do some minor fixes, if necessary, without requiring a new AIRR standards release. Also, this allows services to pin their service to specific API versions.

Two, we fix up the ADC API versions for AIRR v1.4.1 and v1.5.0 and use the new tags.

schristley commented 4 months ago

@javh @bcorrie Any objection for me to clean up the API versions and create tags?

javh commented 4 months ago

No objection from me!

bcorrie commented 4 months ago

Where are you seeing those v.1.4.1 versions?

I see v1.2.0 here (v.1.4.1 tag): https://github.com/airr-community/airr-standards/blob/72e3c3e3ab6e011283522d78ed6384e08baceda5/specs/adc-api-openapi3.yaml#L5

bcorrie commented 4 months ago

We didn't release a new version of the ADC API for v1.5.0 of the AIRR Spec. And this was semi-purposeful because there were no plans to implement any of the changes in v1.5, the plan was to wait for the v2.0 release to change the ADC API. Perhaps we should have done a AIRR v1.5.0 -> ADC v1.3.0 - but we didn't 8-)

So the ADC API spec that is on the v1.5.0 tag is still ADC API v1.2.0 which is tied to v1.4.1 of the spec, which is indeed correctly referenced in the ADC API YAML files.

This is admittedly a bit confusing, but it isn't 100% wrong. The ADC API yaml files are internally consistent (ADC v1.2.0 references the AIRR v.1.4.1 spec). This might be an argument for removing the ADC API spec from the AIRR Standard github and moving it to the CRWG github repository (or a separate ADC github repository). Maybe such a divergence can be handled with tags but it seems like this might get messy.

schristley commented 4 months ago

Where are you seeing those v.1.4.1 versions?

Good question! I used GitHub to change to the tag, then looked at the files, but now I tried to reproduce and failed! Ok, good, I must have been looking at wrong file or something, now that I did it again it seems good.

schristley commented 4 months ago

We didn't release a new version of the ADC API for v1.5.0 of the AIRR Spec. And this was semi-purposeful because there were no plans to implement any of the changes in v1.5, the plan was to wait for the v2.0 release to change the ADC API. Perhaps we should have done a AIRR v1.5.0 -> ADC v1.3.0 - but we didn't 8-)

So the ADC API spec that is on the v1.5.0 tag is still ADC API v1.2.0 which is tied to v1.4.1 of the spec, which is indeed correctly referenced in the ADC API YAML files.

I see. Yeah I was assuming that the API version was increased to support AIRR v1.5.0, but that was never released.