docs: fix upgrade guide

[tmshn]

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
    }
)

[tswast]

(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.

[tswast]

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

[tmshn]

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"?

[tswast]

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

[tswast]

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

[tswast]

Approved. Thank you @tmshn for the contribution!

[gcf-merge-on-green]

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.

[tmshn]

idk why CI doesnt run...