Skip to content
This repository has been archived by the owner on Sep 5, 2023. It is now read-only.

docs: fix upgrade guide #114

Merged
merged 2 commits into from
Feb 19, 2021

Conversation

tmshn
Copy link
Contributor

@tmshn tmshn commented Feb 17, 2021

Current upgrade guide is confusing especially when upgrading from v2.0.0 to v3.0.0 because some of the change is only introduced at v2.0.0. I fixed this.

This is just a documentation fix rather than code fix, so note that following checks are not passed


Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

  • Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
  • Ensure the tests and linter pass
  • Code coverage does not decrease (if any source code was changed)
  • Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> πŸ¦•


Additional question

There are three way to invoke API-calling methods: (1) pass keyword arguments, (2) pass request argument with request class and (3) pass request argument with dict.

The auto-migration tool fixup_datacatalog_v1_keywords.py fixes code to use method (3) even if the methods accepts keyword arguments. However, IMO, it's poorly typed and not linter/autocompletion-friendly.

Actually what is the recommended way? And is there a plan to remove support of method (1)?

Available since Typed Note
(1) v1 β—Ž (since v2)
(2) v2 β–³ Code looks redundant
(3) v2 β˜“

(1)

response = client.create_entry_group(
    parent=parent, 
    entry_group_id=entry_group_id,
    entry_group=entry_group
)

(2)

response = client.create_entry_group(
    datacatalog.CreateEntryGroupRequest(
        parent=parent, 
        entry_group_id=entry_group_id,
        entry_group=entry_group
    )
)

(3)

response = client.create_entry_group(
    request={
        "parent": parent,
        "entry_group_id": entry_group_id,
        "entry_group": entry_group
    }
)

@tmshn tmshn requested a review from a team as a code owner February 17, 2021 06:16
@product-auto-label product-auto-label bot added the api: datacatalog Issues related to the googleapis/python-datacatalog API. label Feb 17, 2021
@google-cla google-cla bot added the cla: yes This human has signed the Contributor License Agreement. label Feb 17, 2021
@tswast
Copy link
Contributor

tswast commented Feb 17, 2021

(2) with the datacatalog.CreateEntryGroupRequest object is what I'd recommend, as it's typed and supports all features.

(1) is the simplest, but some features cannot be used with it.

UPGRADING.md Outdated
## Common Resource Path Helper Methods

| Applicable previous versions |
|:-----------------------------|
| v2.0.0 or lower |
Copy link
Contributor

Choose a reason for hiding this comment

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

This is confusing to me. I believe 2.0 removed location_path, but 3.0 added common_location_path back.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

You mean is:
"Users of v2.0.0 need not to migrate (ie: from their point of view, it's just new feature rather than breaking change)"
right?

So maybe better to write "v1.0.0 or lower"?

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah. I've made a suggested edit to clarify.

UPGRADING.md Outdated Show resolved Hide resolved
UPGRADING.md Outdated
## Common Resource Path Helper Methods

| Applicable previous versions |
|:-----------------------------|
| v2.0.0 or lower |
Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah. I've made a suggested edit to clarify.

@tswast tswast changed the title fix upgrade guide docs: fix upgrade guide Feb 18, 2021
@tswast tswast added the automerge Merge the pull request once unit tests and other checks pass. label Feb 18, 2021
@tswast
Copy link
Contributor

tswast commented Feb 18, 2021

Approved. Thank you @tmshn for the contribution!

@gcf-merge-on-green
Copy link

Merge-on-green attempted to merge your PR for 6 hours, but it was not mergeable because either one of your required status checks failed, one of your required reviews was not approved, or there is a do not merge label. Learn more about your required status checks here: https://help.github.com/en/github/administering-a-repository/enabling-required-status-checks. You can remove and reapply the label to re-run the bot.

@gcf-merge-on-green gcf-merge-on-green bot removed the automerge Merge the pull request once unit tests and other checks pass. label Feb 18, 2021
@tmshn
Copy link
Contributor Author

tmshn commented Feb 19, 2021

idk why CI doesnt run...

@busunkim96 busunkim96 added kokoro:force-run Add this label to force Kokoro to re-run the tests. automerge Merge the pull request once unit tests and other checks pass. labels Feb 19, 2021
@yoshi-kokoro yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Feb 19, 2021
@gcf-merge-on-green gcf-merge-on-green bot merged commit 4bfa587 into googleapis:master Feb 19, 2021
@gcf-merge-on-green gcf-merge-on-green bot removed the automerge Merge the pull request once unit tests and other checks pass. label Feb 19, 2021
@tmshn tmshn deleted the fix-upgrade-guide branch February 19, 2021 18:44
gcf-merge-on-green bot pushed a commit that referenced this pull request Mar 22, 2021
πŸ€– I have created a release \*beep\* \*boop\*
---
## [3.1.0](https://www.github.com/googleapis/python-datacatalog/compare/v3.0.0...v3.1.0) (2021-03-22)


### Features

* add `client_cert_source_for_mtls` argument to transports ([#107](https://www.github.com/googleapis/python-datacatalog/issues/107)) ([59a44bc](https://www.github.com/googleapis/python-datacatalog/commit/59a44bc744a6322a2a23313c851eb77204110e79))


### Bug Fixes

* remove gRPC send/recv limit; add enums to `types/__init__.py` ([#87](https://www.github.com/googleapis/python-datacatalog/issues/87)) ([e0c40c7](https://www.github.com/googleapis/python-datacatalog/commit/e0c40c765242868570532b5074fd239aa2c259e9))


### Documentation

* document enum values with `undoc-members` option ([#93](https://www.github.com/googleapis/python-datacatalog/issues/93)) ([2dbb3ef](https://www.github.com/googleapis/python-datacatalog/commit/2dbb3ef062b52925ad421c5c469ed6e67671e878))
* fix `type_` attribute name in the migration guide ([#113](https://www.github.com/googleapis/python-datacatalog/issues/113)) ([2f98f22](https://www.github.com/googleapis/python-datacatalog/commit/2f98f2244271d92f79fdb26103478166958b8c8a))
* fix upgrade guide ([#114](https://www.github.com/googleapis/python-datacatalog/issues/114)) ([4bfa587](https://www.github.com/googleapis/python-datacatalog/commit/4bfa587903105cb3de2272618374df0b04156017))
* update the upgrade guide to be from 1.0 to 3.0 ([#77](https://www.github.com/googleapis/python-datacatalog/issues/77)) ([eed034a](https://www.github.com/googleapis/python-datacatalog/commit/eed034a3969913e40554300ae97c5e00e4fcc79a))
---


This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
meredithslota added a commit that referenced this pull request Jan 4, 2022
Removed formatted tables (reverts #114)
Converted file back to .MD (reverts part of #268)
meredithslota added a commit that referenced this pull request Jan 10, 2022
* docs: reverts the table addition from #114

Removed formatted tables (reverts #114)
Converted file back to .MD (reverts part of #268)

* docs: revert changes to link

* πŸ¦‰ Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* docs: putting back this section

Owlbot removed this but we need to keep it.

* docs: fix whitespace issue

* πŸ¦‰ Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* rename docs/UPGRADING.rst to docs/UPGRADING.md

* πŸ¦‰ Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: Anthonios Partheniou <partheniou@google.com>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
api: datacatalog Issues related to the googleapis/python-datacatalog API. cla: yes This human has signed the Contributor License Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants