Skip to content

Version increments should distinguish discovery file updates from feature updates #2119

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

Open
jay0lee opened this issue Apr 18, 2023 · 4 comments
Labels
next major: breaking change this is a change that we should wait to bundle into the next major version type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design.
Milestone

Comments

@jay0lee
Copy link
Contributor

jay0lee commented Apr 18, 2023

Today the minor version number is incremented for both true code changes (big fixes, new features) and routine updates to the API discovery docs.

Ideally the version increment would reflect which of these is changing. My suggestion would be to increment patch number (the 0 in 1.86.0) on discovery file only updates and reserve minor version increments for true code changes.

@parthea parthea added the type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design. label Apr 18, 2023
@parthea
Copy link
Contributor

parthea commented Apr 18, 2023

Hello @jay0lee,

This is a great suggestion. I'll pass it along to my team to get their thoughts as well.

We have context aware commits in our Cloud Client Libraries where we provide better release notes. Regretfully, we don't have this infrastructure for clients which are built dynamically from the discovery docs. Please can you clarify if there is anything blocking from migrating to Cloud Client Libraries? As an example, see the release notes for google-cloud-speech here.

@jay0lee
Copy link
Contributor Author

jay0lee commented Apr 18, 2023

Feel free to reach out to me at jayhlee@ if you want to discuss further.

I primarily use this library for Workspace APIs which do not have Cloud client libraries. Frankly I really like the discovery approach of this library and while it does present some stability issues I prefer it as it means new API features are available in the library on day one.

@parthea
Copy link
Contributor

parthea commented Apr 18, 2023

Ideally we would make this versioning change in the next major version. There are a few open issues that may require bumping the major verison:

@parthea parthea added this to the 3.0.0 milestone Apr 18, 2023
@parthea parthea added the next major: breaking change this is a change that we should wait to bundle into the next major version label Apr 18, 2023
@pnico
Copy link

pnico commented May 7, 2023

Please can you clarify if there is anything blocking from migrating to Cloud Client Libraries?

This is OT for this issue, but I see this question - "Why can't you just use our newer libraries" - getting asked a lot. One reason not to use them is their higher memory requirements: googleapis/python-logging#623 (comment)

Another reason I've seen brought up by others is batch operations, which we use extensively.

Until the memory issue is addressed and the client libraries all offer batched operations, there will always be use cases where this library is the better (edit: or even only reasonable) choice. There could very well be other very good reasons.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
next major: breaking change this is a change that we should wait to bundle into the next major version type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design.
Projects
None yet
Development

No branches or pull requests

3 participants