What are breaking and non breaking changes in the context of the Octokit and Terraform SDKs?
While the answer to that question might not always be clear we tend to follow what GitHub considers as breaking changes, while also taking some inspiration from our friends at Square and Stripe.
We use the Semver specification for all of or SDKs.
This means that when breaking changes are introduced we will "bump" the MAJOR version number on the SDK.
To help us detect these types of things we have a label (Type: Breaking change).
There could be a few reasons why you might want to add this label to your Pull Request or Issue. Use the following list to help you better understand if you should add it or not.
- Non-breaking changes:
- Adding new SDK APIs
- Adding optional parameters to existing SDK APIs
- Adding new properties to existing SDK APIs models
- Changing the order of properties in existing SDK APIs models
- Changing the length or format of opaque strings (eg IDs, error messages, other human-readable strings)
- Adding new string constants to enums
- Adding new webhook event types/models
- Deprecating a SDK APIs, response field, or parameter (not removing)
- Breaking changes:
- Adding new required parameters to existing SDK APIs
- Removing an existing SDK API
- Removing a field from a response model
- Renaming a field in a response model
- Changing the type of a response model field or parameter
- Adding a validation rule to an existing parameter
- Changing the HTTP status code returned by an SDK API method
Note: Whenever breaking changes are introduced in the OpenAPI descriptions for the GitHub REST API, there will almost always be a corresponding breaking change in our SDKs