Skip to content

RELEASING.md

Latest commit

 

History

History
175 lines (117 loc) · 4.18 KB

RELEASING.md

File metadata and controls

175 lines (117 loc) · 4.18 KB

Releasing

This document describes the release process for the peelman-kea Puppet module.

Overview

Releases are automated via GitHub Actions. When a version tag (e.g., v0.1.0) is pushed, the CI pipeline runs all tests and, if successful, publishes the module to the Puppet Forge.

Prerequisites

GitHub Secrets

The following secrets must be configured in the repository settings (Settings → Secrets and variables → Actions):

Secret Description
FORGE_API_KEY Puppet Forge API key (generate at https://forge.puppet.com → Profile → API Keys)

Release Process

1. Bump the Version

Use the provided rake tasks to bump the version in metadata.json:

# Patch release (0.0.4 → 0.0.5)
bundle exec rake module:bump:patch

# Minor release (0.0.4 → 0.1.0)
bundle exec rake module:bump:minor

# Major release (0.0.4 → 1.0.0)
bundle exec rake module:bump:major

2. Update CHANGELOG.md

Add a new section for the release version:

## [0.1.0] - YYYY-MM-DD

### Added
- New feature description

### Changed
- Changed behavior description

### Fixed
- Bug fix description

3. Commit and Tag

git add metadata.json CHANGELOG.md
git commit -m "Release v0.1.0"
git push

git tag v0.1.0
git push origin v0.1.0

4. Monitor CI

The tag push triggers the CI pipeline:

  1. Lint - Puppet-lint and metadata validation
  2. Syntax - Puppet syntax validation
  3. Unit Tests - RSpec tests with Puppet 8
  4. Acceptance Tests - Beaker tests on Debian 11/12, Ubuntu 22.04/24.04
  5. Release - Build and publish to Puppet Forge (only on tags)

Monitor progress at: https://github.com/peelman/puppet-kea/actions

5. Verify Release

After CI completes successfully, verify the release at: https://forge.puppet.com/modules/peelman/kea

CI Pipeline

Workflow File

The CI configuration is in .github/workflows/ci.yml.

Triggers

Event Behavior
Push to main Runs lint, syntax, unit, and acceptance tests
Pull request to main Runs lint, syntax, unit, and acceptance tests
Push tag v* Runs all tests, then publishes to Forge

Test Matrix

Job Environment
Lint Ubuntu latest, Ruby 3.2
Syntax Ubuntu latest, Ruby 3.2, Puppet 8
Unit Ubuntu latest, Ruby 3.2, Puppet 8
Acceptance Docker containers: Debian 11/12, Ubuntu 22.04/24.04

Acceptance Test Containers

Acceptance tests use litmusimage containers which have SSH and systemd pre-configured for faster test execution.

Versioning

This project follows Semantic Versioning:

  • MAJOR - Incompatible API changes
  • MINOR - New functionality (backwards compatible)
  • PATCH - Bug fixes (backwards compatible)

Troubleshooting

Release job fails with 401 Unauthorized

  • Verify FORGE_API_KEY secret is set correctly
  • Ensure the API key hasn't expired (regenerate at Forge profile page)
  • The environment variable must be BLACKSMITH_FORGE_API_KEY in the workflow

Release job fails with 409 Conflict

  • The version already exists on the Forge
  • Deleted versions cannot be re-uploaded
  • Bump to a new version number and try again

Acceptance tests timeout

  • Check Docker is available in the CI runner
  • Verify the litmusimage containers are accessible
  • Review Beaker logs in the CI output

Local Testing

Before pushing a release, run the full test suite locally:

# Install dependencies
bundle install

# Run linting
bundle exec rake lint

# Run unit tests
bundle exec rake spec

# Run acceptance tests (requires Docker)
bundle exec rake beaker:debian12

Tools

This module uses puppet-blacksmith for version management and Forge publishing.

Available rake tasks:

bundle exec rake -T | grep module

Key tasks:

  • module:bump:patch - Bump patch version
  • module:bump:minor - Bump minor version
  • module:bump:major - Bump major version
  • module:build - Build the module tarball
  • module:push - Push to Puppet Forge
  • module:release - Full release (bump, tag, push)