AWS CloudControl schema breaking change policy

aws-cloudformation / cloudformation-cli

The CloudFormation Provider Development Toolkit allows you to author your own resource providers and modules that can be used by CloudFormation.

Apache License 2.0

316 stars 157 forks source link

AWS CloudControl schema breaking change policy #1036

Closed bagajjal closed 8 months ago

bagajjal commented 8 months ago

Is the removal of a property from an existing resource type considered a breaking change?
- If so, what is the protocol for notifying users about such modifications?
- If not, how can customers ensure the compatibility of their client applications in the event of schema alterations? Is there a mechanism to receive responses based on the existing schema rather than the current one? Typically, this is achieved through an API versioning approach, but I do not see AWS CloudControl API accepting an api-version input parameter. What guidance does AWS provide regarding this?

Given that AWS does not maintain a Github repository for AWS CloudControl schema, I'm looking to Pulumi for insights into property removal within a specific resource type. According to pulumi (https://github.com/pulumi/pulumi-aws-native/pull/1124), there have been instances of property removals for certain resources.

bagajjal commented 8 months ago

@mircealam, can you please look into this issue.

benbridts commented 8 months ago

This probably does not completely answer your question, but you can mark properties as deprecated in the resource schema:

https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-deprecatedproperties

deprecatedProperties

Resource properties that have been deprecated by the underlying service provider. These properties are still accepted in create and update operations. However they may be ignored, or converted to a consistent model on application. Deprecated properties are not guaranteed to be returned by read operations.

Type: List of JSON pointers

bagajjal commented 8 months ago

@benbridts, I appreciate your response. Regrettably, it doesn't provide the information I'm seeking.

@mircealam, whenever you have a moment, could you kindly provide answers to my questions? Thank you.

bagajjal commented 8 months ago

@mircealam, ping.

mircealam commented 8 months ago

in general, is the removal of a property considered a breaking change? Yes. if your contract changes and you no longer are providing you used to provide that would be considered a breaking change.

Also, in general there should be backwards compatibility and we work really hard to ensure this backwards compatibility.

picking an example from pulumi linked PR for s3 bucket and looking at schema history, I don't see the schema ever specifying an id (but it got somehow in the schema generated by pulumi) so I am not sure where the disconnect is in that specific case.

bagajjal commented 8 months ago

@mircealam,

Pulumi reads the cloud formation schema from https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip and then stores the cloud formation schema in Pulumi repository. Looking at the Pulumi history, the "id" is a deprecated property.

Few follow-up questions,

The addition of new properties is not considered as a breaking change? Even in this case, the contract between client and AWS service changes so ideally it should be treated as a breaking change?
In the event of deprecating properties, is there a way to get the AWS response in the previous schema that has the deprecated properties? AWS CloudControl API doesn't take in API version so I'm not sure.
What is the process for deprecating properties for a resource type?