From dcd86f8dbff0ed0d53165eb7d5d8b92cbaea50b2 Mon Sep 17 00:00:00 2001 From: Brandur Date: Fri, 25 May 2018 20:08:24 +0200 Subject: [PATCH] Add a V32 migration guide Adds a migration guide for the prospective version 32 of stripe-go which will include the changes in #544. Some of the breaking changes there are so sizable that I think we should special-case this with a particular upgrade guide to help ease user pain somewhat while they're upgrading. Here we explain some of the background context and make a list of all the included changes and put in suggestions for remediation. --- v32_migration_guide.md | 146 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 v32_migration_guide.md diff --git a/v32_migration_guide.md b/v32_migration_guide.md new file mode 100644 index 0000000000..12f5aabfde --- /dev/null +++ b/v32_migration_guide.md @@ -0,0 +1,146 @@ +# V32 Migration Guide + +Version 32 of stripe-go contains some very sizable breaking changes. + +The major reason that we moved forward on them is that it was previously +impossible when encoding a parameter struct for an API call to make a +distinction between a field that a user had left unset versus a field that had +been set explicitly, but to an empty value. So if we had a parameter struct +like this: + +``` go +type UsageRecordParams struct { + Quantity uint64 `form:"quantity"` +} +``` + +We were unable to differentiate these two cases: + +``` go +// Initialized with no quantity +UsageRecord {} + +// Initialized with an explicitly zero +UsageRecord { + Quantity: 0, +} +``` + +This is because any uninitialized fields on a struct in Go are set to their +type's "zero value", which for an integer is `0`. + +Working around the problem required a secondary field to help explicitly state +that the zero value was intended, which was quite unintuitive for users: + +``` go +type UsageRecordParams struct { + Quantity uint64 `form:"quantity"` + QuantityZero bool `form:"quantity,zero"` +} + +UsageRecord { + QuantityZero: true, +} +``` + +To address the problem, we moved every parameter struct over to use pointers +instead. So the above becomes: + +``` go +type UsageRecordParams struct { + Quantity *int64 `form:"quantity"` +} +``` + +Because in Go you can't take the address of an inline value (`&0`), we provide +a set of helper functions like `stripe.Int64` specifically for initializing +these structs: + +``` go +UsageRecord { + Quantity: string.Int64(0), +} +``` + +The zero value for pointers is `nil`, so we can now easily determine which +values on a struct were never set, and which ones were explicitly set to a zero +value, thus eliminating the need for the secondary fields like `QuantityZero`. + +Because this is a large change, we also took the opportunity to do some +housekeeping throughout the library. Most of this involves renaming fields and +some resources to be more accurate according to how they're named in Stripe's +REST API, but it also involves some smaller changes like moving some types and +constants around. + +Please see the list below for the complete set of changes. + +## Major changes + +* All fields on parameter structs (those that end with `*Params`) are now + pointers. Please use the new helper functions to set them: + * `stripe.Bool` + * `stripe.Float64` + * `stripe.Int64` + * `stripe.String` + + This also means that extra fields that used to be solely used for tracking + meaningful zero values like `CouponEmpty` and `QuantityZero` have been + dropped. Use their corresponding field (e.g., `Coupon`, `Quantity`) with an + explicit empty value instead (`stripe.String("")`, `stripe.Int64(0)`). +* Many fields have been renamed so that they're more consistent with their name + in Stripe's REST API. Most of the time, this changes abbreviations to a more + fully expanded form. For example: + * `Desc` becomes `Description`. + * `Live` becomes `Livemode`. +* A few names of API resources (and their corresponding parameter and list + classes) have changed: + * `Fee` becomes `ApplicationFee`. + * `FeeRefund` becomes `ApplicationFeeRefund`. + * `Owner` becomes `AdditionalOwner`. + * `Sub` becomes `Subscription`. + * `SubItem` becomes `SubscriptionItem`. + * `Transaction` becomes `BalanceTransaction`. + * `TxFee` becomes `BalanceTransactionFee`. +* Some sets of constants have been renamed and migrated to the top-level + `stripe` package. All constants now have a prefix according to what they + describe (for example, card brands all start with `CardBrand*` like + `CardBrandVisa`) and all now reside in the `stripe` package (for example + `dispute.Duplicate` is now `stripe.DisputeReasonDuplicate`). +* Some structs that used to be shared between requests and responses are now + broken apart. All API calls should be using only structs that end with a + `*Params` suffix. So for example, if you were using `Address` or `DOB` + before, you should now use `AddressParams` and `DOBParams`. + +## Other changes + +* All integer values now use `int64` as their type. This means that the + `stripe.Int64` helper function is appropriate for setting all integer values. + This usually doesn't require a change because just setting these fields to a + numerical literal didn't require that the type be explicitly stated. +* `Event.GetObjValue` becomes `Event.GetObjectValue` +* `Params.AddMeta` becomes `Params.AddMetadata` +* `Params.End` and `ListParams.End` become `EndingBefore`, and become a pointer + (use `stripe.String` to set them as with other parameters). +* `Params.Expand` and `ListParams.Expand` (the fields) becomes a slice of + pointers (instead of a slice of strings). +* `Params.Expand` and `ListParams.Expand` (the functions) become `AddExpand`. +* `Params.IdempotencyKey` becomes a pointer. +* `Params.Limit` becomes a pointer. +* `Params.Meta` becomes `Params.Metadata` +* `Params.Start` and `ListParams.Start` become `StartingAfter` +* `Params.StripeAccount` and `ListParams.StripeAccount` become pointers. +* List object data is now accessed with `object.Data` instead of `object.List`. + Nothing changes if you were using iterators and `Next`. +* The previously deprecated `FileUploadParams.File` has been removed. Please + use `FileUploadParams.FileReader` instead. +* The previously deprecated `Params.Account` has been removed. Please use + `Params.StripeAccount` instead. + +As usual, if you find bugs, please [open them on the repository][issues], or +reach out to `support@stripe.com` if you have any other questions. + +[issues]: https://github.com/stripe/stripe-go/issues/new + +