[in_app_purchase] 0.3.0 Migration guide

[JeroenWeener]

The API changes introduced in 0.3.0 turned out to be bigger and more complicated than anticipated. This migration guide aims to help developers upgrade to 0.3.0 by giving context to the changes and treating some exemplary use cases.

The need for a migration guide was brought to my attention in flutter/flutter#127844.
A follow-up PR will update the README in the app-facing package to align with the breaking changes introduced in 0.3.0, as the current one is out-of-date.

Fixes flutter/flutter#127844

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter. (Unlike the flutter/flutter repo, the flutter/packages repo does use dart format.)
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I listed at least one issue that this PR fixes in the description above.
• I updated pubspec.yaml with an appropriate new version according to the pub versioning philosophy, or this PR is exempt from version changes.
• I updated CHANGELOG.md to add a description of the change, following repository CHANGELOG style.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• All existing and new tests are passing.

[gmackall]

Thanks for adding this guide! I'll block some time to review this this afternoon. Requesting review from @stuartmorgan as well, as you reviewed the initial migration to billing client v5 (let me know if you'd prefer I find a different secondary reviewer Stuart 🙂 ).

[gmackall]

This mostly LGTM, but I want to hold off on approving till I can finish reading through the linked android documentations tomorrow.

[gmackall]

LGTM!

[JeroenWeener]

@gmackall sorry for the inconvenience, but I updated the subscription use cases once more based on feedback in flutter/flutter#127844, as the previous examples missed a crucial detail in fetching subscription offer details.

[stuartmorgan-g]

The content looks great! Other than converting to code excerpts, just a few minor questions.

[stuartmorgan-g]

(Oops, I meant that to be a Request Changes for PR status tracking.)

[gmackall]

Re-adding my approval as this has gone through a couple of changes since my last review, but still LGTM!

I also was not aware of the existence of code-excerpts, but will make sure to recommend them moving forward

[stuartmorgan-g]

LGTM, thanks!

[flutter-dashboard]

It looks like this pull request may not have tests. Please make sure to add tests before merging. If you need an exemption to this rule, contact Hixie on the #hackers channel in Chat (don't just cc him here, he won't see it! He's on Discord!).

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

[Hixie]

test-exempt: documentation

Does it make sense to call this file something more specific? (To put it another way, what do we plan to do when we add a second or third migration guide?)

[stuartmorgan-g]

Does it make sense to call this file something more specific? (To put it another way, what do we plan to do when we add a second or third migration guide?)

If we need more migration guides we would probably put them all in the one file, with top-level sections for each major version, since we don't know what version people will be starting from.

[stuartmorgan-g]

Overriding stale tree status.