Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Undeprecate APIv2 in docs #7579

Merged
merged 2 commits into from Oct 21, 2020
Merged

Undeprecate APIv2 in docs #7579

merged 2 commits into from Oct 21, 2020

Conversation

agjohnson
Copy link
Contributor

APIv2 is still available, we still use it for application operations,
and APIv3 is not quite ready as a replacement for a lot of applications.
I think the docs should reflect that, even if we want new users using
APIv3.

APIv2 is still available, we still use it for application operations,
and APIv3 is not quite ready as a replacement for a lot of applications.
I think the docs should reflect that, even if we want new users using
APIv3.
@agjohnson agjohnson added the Improvement Minor improvement to code label Oct 19, 2020
@agjohnson agjohnson requested a review from a team October 19, 2020 18:30
Copy link
Member

@humitos humitos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not 100% sure that we should remove the deprecation note. I do agree that there are things that are not possible in APIv3 yet, but I think we should improve the message we are communicating here.

docs/api/v2.rst Outdated
the Docs, you should try to use :doc:`API v3 </api/v3>` instead. API v2 is
still used by some application operations still.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should strongly not recommend the usage of APIv2: "you should try" doesn't sound too strong to me 😄

I'd say something like "we don't recommend the usage of APIv2 because we will remove it soon without notification. You should use APIv3 and if there is something that you can't do with APIv3, please contact us"

I don't want new users using APIv2 to do things that are supported on APIv3 and I want users that are forced to use APIv2 to contact us and let us know what's the use case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, a more aggressive stance would be fine here. I just have an issue calling it deprecated.

We need to go through a formal deprecation process with APIv2 still. Right now, it's in a limbo where it says it's deprecated, but it's still fully functional, and APIv3 is not yet a full replacement for APIv2. When APIv3 is ready to be our primary API, then we can call it deprecated, go through a formal process of alerting users and doing rolling brown outs of APIv2, and finally call it deprecated. Right now, we're sending mixed messages and I was a bit confused by this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added firmer language in e776174

Copy link
Member

@humitos humitos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Message is better and clearer now to me! 💯

@agjohnson
Copy link
Contributor Author

Great, and I definitely want to keep up pressure to move to APIv3, but understand it's been hard to get everything through review. Soon!

@agjohnson agjohnson merged commit faef942 into master Oct 21, 2020
2 checks passed
@agjohnson agjohnson deleted the agj/api-v2-docs branch October 21, 2020 15:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Improvement Minor improvement to code
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants