terraform plugin 版本以及changlog 規範

文章來自官方文章，轉自：https://www.terraform.io/docs/extend/best-practices/versioning.html

裡面包含了版本命名的規範，以及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.

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 <code>major</code>.<code>minor</code>.<code>patch</code>, 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 <code>1.0.0</code> signify stronger compatibility guarantees, based on the rules above. each increasing level can also contain changes of the lower level (e.g. <code>minor</code> can contain <code>patch</code> changes).

increasing the <code>major</code> 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. <code>typeset</code> to <code>typelist</code>)

changing attribute format (e.g. changing a timestamp from epoch time to a string)

<code>minor</code> increments are intended to signify the availability of new functionality or deprecations of existing functionality without breaking changes to the previous version.

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. <code>typelist</code> to <code>typeset</code>)

increasing the <code>patch</code> number is intended to signify mainly bug fixes and to be functionally equivalent with the previous version.

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 <code>optional</code> when an attribute can not be configured in the remote api)

fixing attributes to match behavior with the remote api (e.g. changing <code>required</code> to <code>optional</code>, fixing validation)

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 <code>changelog</code> or <code>changelog.md</code>. we generally recommend that the changelog is updated outside of pull requests unless a clear process is setup for handling merge conflicts.

the upcoming release version number is always at the top of the file and is marked specifically as <code>(unreleased)</code>, 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.

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:

each entry under a category should use the following format:

for provider development typically the "subsystem" is the resource or data source affected e.g. <code>resource/load_balancer</code>, or <code>provider</code> 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 <code>[gh-####]</code> (for hashicorp released plugins, this will be automatically updated on release).

to order entries, these basic rules should be followed:

if large cross-cutting changes are present, list them first (e.g. <code>provider</code>)

order other entries lexicographically based on subsystem (e.g. <code>resource/load_balancer</code> then <code>resource/subnet</code>)