Breaking changes for a major release

[jacobbednarz]

We've spoken a couple of times regarding cleaning up the Terraform interface or interactions which would result in breaking backwards compatibility. To discuss how we want to do this and how it will be executed, I've raised this issue.

Here is a table from a quick search on the changes that we'd like to introduce:

Change	Discussion link	Reason
Swap org_id for account_id	https://github.com/terraform-providers/terraform-provider-cloudflare/pull/226#pullrequestreview-209887811	Move off deprecated APIs and use newer nomenclature
Deprecate zone_name in favour of zone_id	https://github.com/terraform-providers/terraform-provider-cloudflare/issues/161#issuecomment-441128985	More explicitness as domain name isn't unique but ID is.

I'll keep this table updated so if you have other things to add please pop them below and I'll update this accordingly.

Once we decide on what we want to change, I'll create a new milestone and we can start picking off the tasks to complete.

cc @patryk @garrettgalow @prdonahue

[garrettgalow]

Based on #109 we should focus on zone_name -> zone_id.

To clarify, from the customer's perspective, Is org_id -> account_id just changing the single var name in the provider configuration?

[jacobbednarz]

To clarify, from the customer's perspective, Is org_id -> account_id just changing the single var name in the provider configuration?

Yep! End users will only have that single thing to change but there will need to be a bit of shuffling in the provider.

[garrettgalow]

It would likely be ideal to shift zone name to id in a staged approached - aka allowing any resource with zone name to instead use zone id and then at a later time remove the zone_name fields - not sure how feasible that is.

if we have to make breaking changes for TF .12 then it would be a good time for these things, but if not I'm still in favor of scheduling time for them - I'd like to kill off orgs sometime this year, and this would be one of the checkboxes on the list

[jacobbednarz]

It would likely be ideal to shift zone name to id in a staged approached - aka allowing any resource with zone name to instead use zone id and then at a later time remove the zone_name fields - not sure how feasible that is.

We can definitely make it possible for both values to be present in the schema as is (with some deprecation warnings) and then in a later version just deprecate the one we no longer want.

if we have to make breaking changes for TF .12 then it would be a good time for these things, but if not I'm still in favor of scheduling time for them

I'd like to avoid having too many big things change at once and I think the 0.12 terraform upgrade warrants being done on it's own. If we do a couple of larger breaking changes at once, we have the possibility of expelling quite a bit of energy of debugging which issue we're battling and from experience, that makes things quite a lot harder. I think it's also good to separate the work on terraform core (such as the 0.12 upgrade) and the provider itself.

[jacobbednarz]

@garrettgalow Are you able to elaborate on what killing off orgs will entail? I've got some changes at the moment updating all the references to "orgs" to move to the "accounts" equivalents so can wrap it up in the same PR if you'd like?

[garrettgalow]

if terraform starts calling equivalent /accounts apis instead of /organizations for endpoints like workers, pools, etc then that is sufficient for TF - along with updating the provider variable name. For users no change is needed since the ids themselves are the same. I don't know of any breaking changes between org and account endpoints for sub resources as internally we proxy both to the same place.

[jacobbednarz]

great! that is pretty much what I was going to do s/organisations/accounts/ so I think that should work perfectly here. Will ping you on the PR when it’s ready.

[jacobbednarz]

tackling the organization deprecation in cloudflare-go via cloudflare/cloudflare-go#315

[jacobbednarz]

deprecation notice for zone has been added in #421.

[jacobbednarz]

org => account move is happening in #451