terraform plugin 版本以及changlog 规范
Given the breadth of available Terraform plugins, ensuring a consistent experience across them requires a standard guideline for compatibility promises. These guidelines are enforced for plugins released by HashiCorp and are recommended for all community plugins.
»Versioning Specification
Observing that Terraform plugins are in many ways analogous to shared libraries in a programming language, we adopted a version numbering scheme that follows the guidelines of Semantic Versioning. In summary, this means that with a version number of the form MAJOR.MINOR.PATCH, the following meanings apply:
- Increasing only the patch number suggests that the release includes only bug fixes, and is intended to be functionally equivalent.
- Increasing the minor number suggests that new features have been added but that existing functionality remains broadly compatible.
- Increasing the major number indicates that significant breaking changes have been made, and thus extra care or attention is required during an upgrade.
Version numbers above 1.0.0 signify stronger compatibility guarantees, based on the rules above. Each increasing level can also contain changes of the lower level (e.g. MINOR can contain PATCH changes).
»Example Major Number Increments
Increasing the MAJOR number is intended to signify potentially breaking changes.
Within Terraform provider development, some examples include:
- Removing a resource or data source
- Removing an attribute
- Renaming a resource or data source
- Renaming an attribute
- Changing fundamental provider behaviors (e.g. authentication or configuration precedence)
- Changing resource import ID format
- Changing resource ID format
- Changing attribute type where the new type is functionally incompatible (e.g.
TypeSettoTypeList) - Changing attribute format (e.g. changing a timestamp from epoch time to a string)
»Example Minor Number Increments
MINOR increments are intended to signify the availability of new functionality or deprecations of existing functionality without breaking changes to the previous version.
Within Terraform provider development, some examples include:
- Marking a resource or data source as deprecated
- Marking an attribute as deprecated
- Adding a new resource or data source
- Aliasing an existing resource or data source
- Implementing new attributes within the provider configuration or an existing resource or data source
- Implementing new validation within an existing resource or data source
- Changing attribute type where the new type is functionally compatible (e.g.
TypeListtoTypeSet)
»Example Patch Number Increments
Increasing the PATCH number is intended to signify mainly bug fixes and to be functionally equivalent with the previous version.
Within Terraform provider development, some examples include:
- Fixing an interaction with the remote API or Terraform state drift detection (e.g. broken create, read, update, or delete functionality)
- Fixing attributes to match behavior with resource code (e.g. removing
Optionalwhen an attribute can not be configured in the remote API) - Fixing attributes to match behavior with the remote API (e.g. changing
RequiredtoOptional, fixing validation)
»Changelog Specification
For better operator experience, we provide a standardized format so development information is available across all providers consistently. The changelog should live in a top level file in the project, named CHANGELOG or CHANGELOG.md. We generally recommend that the changelog is updated outside of pull requests unless a clear process is setup for handling merge conflicts.
»Version Headers
The upcoming release version number is always at the top of the file and is marked specifically as (Unreleased), with other previously released versions below.
NOTE: For HashiCorp released providers, the release process will replace the "Unreleased" header with the current date. This line must be present with the target release version to successfully release that version.
## X.Y.Z (Unreleased)
...
## A.B.C (Month Day, Year)
...
»Categorization
Information in the changelog should broken down as follows:
- BACKWARDS INCOMPATIBILITIES or BREAKING CHANGES: This section documents in brief any incompatible changes and how to handle them. This should only be present in major version upgrades.
- NOTES: Additional information for potentially unexpected upgrade behavior, upcoming deprecations, or to highlight very important crash fixes (e.g. due to upstream API changes)
- FEATURES: These are major new improvements that deserve a special highlight, such as a new resource or data source.
- IMPROVEMENTS or ENHANCEMENTS: Smaller features added to the project such as a new attribute for a resource.
- BUG FIXES: Any bugs that were fixed.
These should be displayed as left aligned text with new lines above and below:
CATEGORY:
»Entry Format
Each entry under a category should use the following format:
* subsystem: Descriptive message [GH-1234]
For provider development typically the "subsystem" is the resource or data source affected e.g. resource/load_balancer, or provider if the change affects whole provider (e.g. authentication logic). Each bullet also references the corresponding pull request number that contained the code changes, in the format of [GH-####] (for HashiCorp released plugins, this will be automatically updated on release).
»Entry Ordering
To order entries, these basic rules should be followed:
- If large cross-cutting changes are present, list them first (e.g.
provider) - Order other entries lexicographically based on subsystem (e.g.
resource/load_balancerthenresource/subnet)
»Example Changelog
## 1.0.0 (Unreleased)
BREAKING CHANGES:
* Resource `network_port` has been removed [GH-1]
FEATURES:
* **New Resource:** `cluster` [GH-43]
IMPROVEMENTS:
* resource/load_balancer: Add `ATTRIBUTE` argument (support X new functionality) [GH-12]
* resource/subnet: Now better [GH-22, GH-32]
## 0.2.0 (Month Day, Year)
FEATURES:
...
