Skip to content

RELEASING.md

Latest commit

 

History

History
223 lines (161 loc) · 5.95 KB

RELEASING.md

File metadata and controls

223 lines (161 loc) · 5.95 KB

Release Process

This project uses release-please for automated releases and changelog generation.

How It Works

Release-please automatically:

  1. Creates release PRs based on conventional commits
  2. Updates the CHANGELOG.md
  3. Bumps the version in Cargo.toml
  4. Creates GitHub releases
  5. Publishes to crates.io (when configured)

Conventional Commits

Use conventional commits format for your commit messages:

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

  • feat: A new feature (bumps minor version)
  • fix: A bug fix (bumps patch version)
  • docs: Documentation only changes
  • style: Changes that don't affect code meaning (formatting, etc.)
  • refactor: Code changes that neither fix bugs nor add features
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Changes to build system or dependencies
  • ci: Changes to CI configuration
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit

Breaking Changes

To indicate a breaking change (bumps major version):

feat!: remove deprecated API method

BREAKING CHANGE: The old API method has been removed. Use the new method instead.

Or simply use ! after the type/scope:

feat(api)!: change response format

Examples

# Feature addition
feat: add support for ESPHome API 1.13
feat(discovery): implement timeout configuration

# Bug fix
fix: correct connection timeout handling
fix(noise): resolve handshake failure on retry

# Documentation
docs: update README with new examples
docs(api): add missing parameter descriptions

# Breaking change
feat!: redesign client builder API

BREAKING CHANGE: The builder pattern has been redesigned. 
Update your code to use the new `.address()` method instead of `.with_addr()`.

Release Workflow

1. Develop and Commit

Make your changes and commit using conventional commit messages:

git add .
git commit -m "feat: add new sensor type support"
git push origin main

2. Automatic PR Creation

When commits are pushed to main, release-please will:

  • Analyze commits since the last release
  • Determine the next version based on commit types
  • Create or update a release PR

3. Review and Merge

  • Review the automatically generated changelog in the release PR
  • Check that the version bump is appropriate
  • Merge the PR when ready to release

4. Automatic Release

After merging the release PR:

  • A GitHub release is automatically created
  • The package is published to crates.io (if CARGO_REGISTRY_TOKEN is configured)
  • Release artifacts are uploaded

Configuration Files

.release-please-manifest.json

Tracks the current version of the package.

release-please-config.json

Configures how release-please behaves:

  • Package name
  • Release type (rust)
  • Changelog sections
  • Version bump strategy

Setup for Publishing

1. Get a crates.io API Token

  1. Log in to crates.io
  2. Go to Account Settings → API Tokens
  3. Create a new token with "Publish new crates" permission

2. Add Token to GitHub Secrets

  1. Go to your repository Settings → Secrets and variables → Actions
  2. Add a new secret named CARGO_REGISTRY_TOKEN
  3. Paste your crates.io API token

3. Verify Cargo.toml Metadata

Ensure your Cargo.toml has complete metadata:

[package]
name = "esphome-client"
version = "0.1.0"  # This will be updated automatically
description = "ESPHome client library for Rust"
license = "MIT"
repository = "https://github.com/daanoz/esphome-client"
homepage = "https://github.com/daanoz/esphome-client"
documentation = "https://docs.rs/esphome-client"
readme = "README.md"
keywords = ["esphome", "iot", "smart-home", "home-automation", "api"]
categories = ["network-programming", "api-bindings"]

Manual Release (Emergency)

If you need to manually trigger a release:

  1. Update version in Cargo.toml
  2. Update CHANGELOG.md
  3. Update .release-please-manifest.json
  4. Create a git tag: 
    git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0
  5. Publish to crates.io: 
    cargo publish

Version Strategy

This project follows Semantic Versioning:

  • Major (x.0.0): Breaking changes (e.g., feat!: or BREAKING CHANGE:)
  • Minor (0.x.0): New features (e.g., feat:)
  • Patch (0.0.x): Bug fixes (e.g., fix:)

Before 1.0.0:

  • Minor version bumps may include breaking changes
  • Patch version bumps are for bug fixes and non-breaking features

After 1.0.0:

  • Strict semantic versioning applies
  • Breaking changes require major version bump

Troubleshooting

Release PR Not Created

  • Check that commits follow conventional commit format
  • Ensure commits are pushed to the main branch
  • Look at workflow runs in Actions tab for errors

Release Failed to Publish

  • Verify CARGO_REGISTRY_TOKEN secret is set correctly
  • Check that package name is available on crates.io
  • Ensure all required metadata is in Cargo.toml
  • Verify the package builds successfully: cargo publish --dry-run

Version Conflict

If there's a version mismatch:

  1. Update .release-please-manifest.json to match Cargo.toml
  2. Commit and push
  3. Release-please will sync on next run

Best Practices

  1. One logical change per commit - Makes changelog more readable
  2. Descriptive commit messages - They become your changelog
  3. Test before merging - CI should pass before merging release PRs
  4. Review changelogs - Check generated changelog for accuracy
  5. Document breaking changes - Include migration guide in commit body

Resources