Versioning & Releases

7 minute read

Semantic Versioning

Terraform providers follow Semantic Versioning (SemVer) for version management.

Version Format

MAJOR.MINOR.PATCH

Example: 1.2.3
         │ │ └── PATCH: Bug fixes, backward compatible
         │ └──── MINOR: New features, backward compatible  
         └────── MAJOR: Breaking changes

Version Components

MAJOR (Breaking Changes):

  • Remove or rename resources/data sources
  • Remove or rename attributes
  • Change attribute types
  • Change validation rules (more restrictive)
  • Change default values (incompatible)

MINOR (New Features):

  • Add new resources/data sources
  • Add new optional attributes
  • Add new computed attributes
  • Deprecate (but not remove) features
  • Change validation rules (less restrictive)

PATCH (Bug Fixes):

  • Fix bugs
  • Update documentation
  • Improve error messages
  • Performance improvements
  • No user-facing changes

Version Lifecycle

Development Phase (0.x.x)

v0.1.0  # Initial alpha release
v0.2.0  # Add more resources
v0.3.0  # Add data sources
v0.9.0  # Feature complete
v0.9.1  # Bug fixes

Characteristics:

  • Breaking changes allowed in minor versions
  • API unstable
  • Not recommended for production
  • Fast iteration

Stable Phase (1.x.x+)

v1.0.0  # First stable release
v1.1.0  # New features (backward compatible)
v1.2.0  # More features
v1.2.1  # Bug fix
v2.0.0  # Breaking changes

Characteristics:

  • Breaking changes only in major versions
  • API stable
  • Production-ready
  • Careful change management

Version Examples

PATCH Release (1.2.3 → 1.2.4)

Changes:

  • Fix bug in cache deletion
  • Update documentation typos
  • Improve error messages
## [1.2.4] - 2026-07-01

### Fixed
- Fixed issue where cache deletion timeout was not respected (#123)
- Corrected documentation example for multi-AZ configuration
- Improved error message when API key is invalid

MINOR Release (1.2.4 → 1.3.0)

Changes:

  • Add new backup_window attribute
  • Add new data source cachecloud_engine_versions
  • Deprecate legacy_mode attribute
## [1.3.0] - 2026-07-15

### Added
- New `backup_window` attribute for specifying backup times (#130)
- New data source `cachecloud_engine_versions` for querying supported versions (#132)
- Support for Redis 7.0 (#135)

### Deprecated
- `legacy_mode` attribute deprecated in favor of `mode` (#140)

### Fixed
- Cache status updates now refresh correctly (#138)

MAJOR Release (1.3.0 → 2.0.0)

Changes:

  • Remove deprecated legacy_mode attribute
  • Rename num_nodes to node_count
  • Change port type from String to Number
## [2.0.0] - 2026-08-01

### Breaking Changes
- **Removed** `legacy_mode` attribute (deprecated in 1.3.0). Use `mode` instead.
- **Renamed** `num_nodes` attribute to `node_count` for consistency (#145)
- **Changed** `port` type from String to Number (#147)

### Migration Guide

#### legacy_mode Removal

Before (v1.x):
```terraform
resource "cachecloud_cache" "example" {
  legacy_mode = true
}

After (v2.x):

resource "cachecloud_cache" "example" {
  mode = "legacy"
}

num_nodes Rename

Before:

num_nodes = 3

After:

node_count = 3

port Type Change

Before:

port = "6379"

After:

port = 6379  # Now a number

Added

  • Support for cluster mode (#150)
  • New cluster_configuration block (#151)

Fixed

  • Improved state drift detection (#155) ```

Pre-release Versions

Alpha Releases

Early testing, unstable:

v0.1.0-alpha.1
v0.1.0-alpha.2
v0.1.0-alpha.3

Beta Releases

Feature complete, testing:

v0.1.0-beta.1
v0.1.0-beta.2

Release Candidates

Production-ready candidates:

v1.0.0-rc.1
v1.0.0-rc.2
v1.0.0-rc.3

Final Release

v1.0.0

Changelog Management

Changelog Format

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Feature under development

## [1.3.0] - 2026-07-15

### Added
- New `backup_window` attribute for scheduling backups (#130)
- Data source `cachecloud_engine_versions` (#132)
- Support for Redis 7.0 (#135)

### Changed
- Default Redis version changed from 6.2 to 7.0 (#136)
- Improved cache creation performance by 30% (#137)

### Deprecated
- `legacy_mode` attribute will be removed in 2.0 (#140)

### Fixed
- Cache status updates now refresh correctly (#138)
- Import now handles multi-region caches (#139)

### Security
- Updated dependencies to address CVE-2026-12345 (#141)

## [1.2.4] - 2026-07-01

### Fixed
- Fixed cache deletion timeout issue (#123)
- Corrected multi-AZ documentation example (#124)

## [1.2.0] - 2026-06-15

### Added
- Multi-AZ support (#110)
- Automatic failover configuration (#111)

[Unreleased]: https://github.com/example/terraform-provider-cachecloud/compare/v1.3.0...HEAD
[1.3.0]: https://github.com/example/terraform-provider-cachecloud/compare/v1.2.4...v1.3.0
[1.2.4]: https://github.com/example/terraform-provider-cachecloud/compare/v1.2.0...v1.2.4
[1.2.0]: https://github.com/example/terraform-provider-cachecloud/releases/tag/v1.2.0

Changelog Categories

Added: New features

### Added
- New resource `cachecloud_cluster`
- Support for Memcached engine

Changed: Modifications to existing functionality

### Changed
- Default node type changed from t2.micro to t3.micro
- Timeout increased from 5m to 10m

Deprecated: Features scheduled for removal

### Deprecated
- `old_attribute` is deprecated, use `new_attribute` instead
- Will be removed in version 2.0.0

Removed: Deleted features

### Removed
- Removed `legacy_mode` attribute (deprecated in 1.5.0)

Fixed: Bug fixes

### Fixed
- Fixed issue where tags were not applied on creation
- Corrected state refresh logic

Security: Security fixes

### Security
- Updated golang.org/x/crypto to v0.14.0 (CVE-2026-12345)

Git Tags and Releases

Creating a Release

# Update version in code
# Update CHANGELOG.md
# Commit changes
git add .
git commit -m "Release v1.3.0"

# Create signed tag
git tag -s v1.3.0 -m "Release v1.3.0"

# Push tag
git push origin v1.3.0

Tag Naming

# ✅ Good: Semantic versioning with 'v' prefix
v1.0.0
v1.2.3
v2.0.0-beta.1

# ❌ Bad: Non-standard formats
1.0.0       # Missing 'v' prefix
v1          # Not semantic version
latest      # Not a version number

Signing Tags

# Generate GPG key (if not already done)
gpg --full-generate-key

# List keys
gpg --list-secret-keys --keyid-format=long

# Configure Git to use GPG key
git config --global user.signingkey ABCD1234

# Create signed tag
git tag -s v1.0.0 -m "Release v1.0.0"

# Verify signed tag
git tag -v v1.0.0

Version Constraints

User Perspective

Users specify version constraints in Terraform:

terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      
      # Exact version
      version = "1.2.3"
      
      # Minimum version
      version = ">= 1.2.0"
      
      # Version range
      version = ">= 1.2.0, < 2.0.0"
      
      # Pessimistic constraint (~>)
      version = "~> 1.2"    # >= 1.2.0, < 1.3.0
      version = "~> 1.2.0"  # >= 1.2.0, < 1.3.0
      version = "~> 1.2.3"  # >= 1.2.3, < 1.3.0
    }
  }
}

Constraint Operators

Operator Meaning Example Matches
= Exact = 1.2.3 1.2.3 only
!= Not equal != 1.2.3 Any except 1.2.3
> Greater than > 1.2.0 1.2.1, 1.3.0, 2.0.0
>= Greater or equal >= 1.2.0 1.2.0, 1.2.1, 1.3.0
< Less than < 2.0.0 1.x.x
<= Less or equal <= 1.2.3 1.2.3, 1.2.2, 1.0.0
~> Pessimistic ~> 1.2 >= 1.2.0, < 1.3.0

Deprecation Strategy

Deprecation Process

  1. Announce deprecation in minor release
  2. Document alternative in changelog
  3. Warn users in logs/documentation
  4. Remove in next major release

Example Deprecation

Version 1.5.0 (Announce):

// internal/provider/cache_resource.go
"legacy_mode": schema.BoolAttribute{
    Optional: true,
    DeprecationMessage: "This attribute is deprecated and will be removed in version 2.0. " +
        "Use 'mode' attribute instead.",
    Description: "Enable legacy compatibility mode (deprecated).",
},

"mode": schema.StringAttribute{
    Optional:    true,
    Description: "Cache mode. Valid values: 'standard', 'legacy'.",
},

CHANGELOG.md:

## [1.5.0] - 2026-09-01

### Deprecated
- `legacy_mode` attribute is deprecated. Use `mode = "legacy"` instead.
  Will be removed in version 2.0.0.

### Added
- New `mode` attribute to replace `legacy_mode`

Version 2.0.0 (Remove):

// legacy_mode removed from schema

"mode": schema.StringAttribute{
    Optional:    true,
    Description: "Cache mode. Valid values: 'standard', 'legacy'.",
    Validators: []validator.String{
        stringvalidator.OneOf("standard", "legacy"),
    },
},

CHANGELOG.md:

## [2.0.0] - 2026-12-01

### Breaking Changes
- **Removed** `legacy_mode` attribute (deprecated in 1.5.0)
  
### Migration Guide

Replace `legacy_mode`:

Before (v1.x):
```terraform
resource "cachecloud_cache" "example" {
  legacy_mode = true
}

After (v2.x):

resource "cachecloud_cache" "example" {
  mode = "legacy"
}


## Release Process

### 1. Prepare Release

```bash
# Create release branch
git checkout -b release/v1.3.0

# Update version
# - Update CHANGELOG.md
# - Update README.md if needed
# - Update version in code

# Commit changes
git add .
git commit -m "Prepare release v1.3.0"

2. Test Release

# Run all tests
make test
make testacc

# Build provider
make build

# Test locally
terraform init
terraform plan
terraform apply

3. Create and Push Tag

# Merge to main
git checkout main
git merge release/v1.3.0

# Create signed tag
git tag -s v1.3.0 -m "Release v1.3.0

- New backup_window attribute
- Support for Redis 7.0
- Bug fixes and improvements"

# Push changes and tag
git push origin main
git push origin v1.3.0

4. GitHub Release

GitHub Actions automatically creates release when tag is pushed (covered in next chapter).

Version Matrix

Maintaining Multiple Versions

main (development) ─────────────────────────────▶ v2.1.0
                         │
                         ├─── release/2.0.x ───▶ v2.0.5
                         │
                         └─── release/1.x ─────▶ v1.5.10

Support Strategy:

  • Latest major: Full support (new features + bug fixes)
  • Previous major: Bug fixes only
  • Older versions: Security fixes only

Best Practices

1. Clear Version Bumps

# ✅ Good: Appropriate version bumps
v1.2.3 → v1.2.4  # Bug fix
v1.2.4 → v1.3.0  # New feature
v1.3.0 → v2.0.0  # Breaking change

# ❌ Bad: Inappropriate version bumps
v1.2.3 → v1.2.5  # Skipped version
v1.2.3 → v2.0.0  # Breaking change without prior deprecation
v1.2.3 → v1.3.5  # Multiple changes combined

2. Comprehensive Changelogs

# ✅ Good: Detailed, categorized
## [1.3.0] - 2026-07-15

### Added
- New `backup_window` attribute for backup scheduling (#130)
- Support for Redis 7.0 (#135)

### Fixed
- Cache status updates refresh correctly (#138)

# ❌ Bad: Vague
## [1.3.0]
- Various updates and fixes

3. Deprecation Timeline

# ✅ Good: Clear timeline
v1.5.0: Deprecate `legacy_mode` (announcement)
v1.6.0: Add migration guide
v1.7.0: Final warning
v2.0.0: Remove `legacy_mode`

# ❌ Bad: Immediate removal
v1.5.0: Add `mode` attribute
v1.6.0: Remove `legacy_mode` (breaking change in minor version!)

Key Takeaways

  • ✅ Follow semantic versioning strictly
  • ✅ Maintain comprehensive changelogs
  • ✅ Use signed git tags
  • ✅ Plan deprecations carefully
  • ✅ Provide migration guides for breaking changes
  • ✅ Test thoroughly before release
  • ✅ Support version constraints
  • ✅ Document version support policy
  • ✅ Communicate breaking changes clearly
  • ✅ Use pre-release versions for testing

What’s Next?

Learn how to automate your release process with GoReleaser and GitHub Actions.

Next: Release Automation →

Previous: ← Terraform Registry
Next: Release Automation →

Last updated: June 30, 2026

Updated:

You may also enjoy