Rails Engine Release

Use this skill when the task is to ship a Rails engine as a gem or prepare a new version.

Release work should make upgrades predictable for host applications.

Quick Reference

HARD-GATE

DO NOT release without updating CHANGELOG and version file.

Release Order

1. Confirm the scope of change.
2. Classify compatibility impact.
3. Set the version bump.
4. Update changelog and upgrade notes.
5. Verify gemspec metadata and dependencies.
6. Confirm tests and installation docs match the release.

Versioning Rules

• Patch: bug fixes and internal changes without public behavior breakage.
• Minor: backward-compatible features and new extension points.
• Major: breaking changes to API, setup, routes, migrations, configuration, or supported framework versions.

If the engine requires host changes during upgrade, document them explicitly even if the version bump is minor.

Common Mistakes

Red Flags

• Major version bump without migration guide or upgrade notes
• Deprecated code removed without a prior deprecation cycle and replacement path
• No gem push verification (e.g., dry-run or staging check before publishing)
• Changelog written from git log instead of user-facing impact

Release Checklist

• gemspec metadata is current
• version constant updated once
• changelog reflects user-visible changes
• deprecations documented with removal plan
• migration or install changes called out
• README/setup instructions still accurate

Upgrade Notes Should Include

• required host code changes
• migration steps
• configuration additions or removals
• compatibility changes for Rails/Ruby versions
• deprecation replacements

Review Triggers

• silent breaking changes
• missing upgrade notes for migrations or configuration changes
• gemspec constraints inconsistent with tested versions
• changelog written from implementation details instead of user impact

Examples

Changelog entry (user impact, not implementation):

## [1.2.0] - 2024-03-15
### Added
- Configuration option `widget_count` to limit dashboard widgets (default: 10).
### Changed
- Minimum Rails version is now 7.0.
### Fixed
- Engine routes no longer conflict with host `root_path` when mounted at `/`.

Upgrade note for host app:

### Upgrading from 1.1.x to 1.2.0
1. Run `bundle update my_engine`.
2. If you override the dashboard, add `MyEngine.config.widget_count = 10` to your initializer (optional).
3. Ensure Rails >= 7.0.

Output Style

When asked to prepare a release:

1. Recommend the version bump and why.
2. Draft concise changelog entries.
3. Draft upgrade notes for host apps.
4. Call out any release blockers clearly.

Integration