Semverve

Rake tasks for handling the tedium surrounding maintaining a version number in your Ruby project, with gusto!

About

Maintaining a gem version is not hard, but there are so many little pieces that are easy to forget. How many times have you had changes where the code was ready, the tests were green, the PR was merged, you go to push the gem, and you realize you forgot to bump the version? Then comes the tiny follow-up PR that forces you to waste CI minutes for a two-line change, you submit it, and... oh, no! You still have references to the old version number in your documentation! Rinse and repeat until you finally remember all the things.

Semverve is meant to make that tedium boring in the best way. It provides a small set of Rake tasks for reading the current version, generating a version file, incrementing patch/minor/major versions, setting an exact version, and checking the places where version numbers tend to drift, like .gemspec files and documentation.

In a nutshell, rake semverve:increment:patch updates the "patch" level in your configured version.rb file, :minor updates the "minor" level, etc.. Calling rake semverve:check checks whether the surrounding project still agrees with that version. It can catch stale README references, safe code literals, .gemspec drift, and a stale Gemfile.lock entry. If you want Semverve to do the mechanical cleanup, the matching *:fix tasks can update safe references and run bundle lock for generated lockfile drift. Specific findings can be skipped with magic comments, similar to RuboCop and RDoc.

You can view the documentation here.

For release history and upgrading notes, see CHANGELOG.md.

Installation

Add the gem to your Gemfile:

gem"semverve"

Then add this to your Rakefile:

require"semverve/task"Semverve::Task.new

This defines:

rake semverve:current
rake semverve:increment:patch
rake semverve:increment:minor
rake semverve:increment:major
rake semverve:generate
rake 'semverve:set[1.2.3]'
rake semverve:check
rake semverve:fix
rake semverve:check:references
rake semverve:fix:references
rake semverve:check:code
rake semverve:fix:code
rake semverve:check:package_metadata
rake semverve:fix:package_metadata
rake semverve:check:rails_config_metadata
rake semverve:fix:rails_config_metadata
rake semverve:check:rubygems
rake semverve:check:release

Configuration

By default, Semverve reads the single .gemspec in the project root, uses spec.name as the gem name, and manages lib/<gem_name>/version.rb.

For a conventional gem, this may be all you need:

require"semverve/task"Semverve::Task.new

That installs the semverve:* Rake tasks. If you want to change any defaults, configure Semverve from the task block in your Rakefile:

require"semverve/task"Semverve::Task.newdo |config|
config.format=:moduleconfig.bundle_lock=trueconfig.version_file="lib/my_gem/version.rb"config.module_name="MyGem"config.version_checks=[:doc_references,:code_references,:package_metadata]config.release_checks=[:rubygems]config.rubygems_host="https://rubygems.org"config.version_code_reference_files.append("lib/**/*.rb")config.version_doc_reference_files.append("doc/**/*.md")config.version_match_mode=:non_currentend

The core defaults are equivalent to:

Semverve::Task.newdo |config|
config.adapter=nilconfig.format=:moduleconfig.bundle_lock=falseconfig.root=Dir.pwdconfig.version_checks=[:doc_references,:code_references,:package_metadata]config.release_checks=[]config.rubygems_host="https://rubygems.org"config.task_namespace=:semverveconfig.version_match_mode=:olderconfig.version_code_reference_files=Rake::FileList[]config.version_code_reference_pattern=/^\s*(?:(?:[A-Z]\w*::)*(?:[A-Z]\w*VERSION[A-Z0-9_]*|VERSION)|(?:[a-z_]\w*|self)\.version)\s*=\s*(?<quote>["'])(?<version>\d+\.\d+\.\d+)\k<quote>/config.version_doc_reference_files=Rake::FileList["README*","**/README*"].exclude(".git/**/*","coverage/**/*","tmp/**/*","vendor/**/*")end

The empty version_code_reference_files default only applies to arbitrary code literal scanning. rake semverve:check still checks the resolved .gemspec version and matching Gemfile.lock entry through its default package metadata check. Release checks are empty by default because they may make network requests and are intended for release pipelines rather than every local or pull-request run.

Set config.task_namespace in the task block to use a shorter or project-specific namespace:

require"semverve/task"Semverve::Task.newdo |config|
config.task_namespace=:versionend

That installs tasks such as version:current, version:increment:patch, and version:check instead of semverve:*.

Semverve tasks use Rake task arguments for values:

rake 'semverve:set[1.2.3]'
rake 'semverve:generate[1.0.0,simple]'
rake 'semverve:generate[simple]'
rake 'semverve:generate[force]'

Quote task invocations that include square brackets. Shells such as zsh may otherwise treat brackets as glob patterns before Rake sees them. Flag syntax such as rake semverve:set --version 1.2.3 is not used because --version is already a Rake option; Semverve stays within Rake's native argument syntax instead.

The gem name, module name, and version-file path are inferred by default:

config.gem_name# spec.name from the single .gemspecconfig.module_name# camelized gem name, such as "MyGem"config.version_file# lib/<gem_name>/version.rb

Override them when your project does something unusual:

Semverve::Task.newdo |config|
config.gem_name="my-gem"config.module_name="MyGem"config.version_file="lib/my_gem/version.rb"end

Framework adapters

Framework adapters provide app-oriented defaults without requiring a gemspec or package identity. config.adapter is the preferred API; config.preset remains supported as a backward-compatible alias.

Rails apps

Rails applications do not need gem-style version files, but an application version can still be useful for release notes, support/debug screens, deployment metadata, or API output.

When Rails is loaded, Semverve's Railtie installs the same semverve:* Rake tasks for bin/rails/rails automatically. To use Rails-style defaults, set the Rails adapter:

Semverve::Task.newdo |config|
config.adapter=:railsend

config.preset = :rails is still accepted for existing setups.

The Rails adapter uses Rails.root, stores the version in config/version.rb, uses the :simple format, and infers the module name from your Rails application module when possible. Its default checks are app-oriented: documentation references, configured code literals, and optional Rails config metadata. It does not run package metadata checks unless you opt in.

Generate the file with:

bin/rails semverve:generate

If your app keeps the version somewhere else, override the path:

Semverve::Task.newdo |config|
config.adapter=:railsconfig.version_file="config/releases/version.rb"end

Rails support is only an adapter and a Railtie; Semverve does not require a dummy app, a Rails plugin layout, or a Rails dependency.

Rails config metadata is optional. When present, Semverve checks safe literals in config/application.rb, config/environments/*.rb, and config/initializers/**/*.rb:

config.x.version="1.2.2"Rails.application.config.x.version="1.2.2"

Dynamic assignments are treated as self-managed and left alone:

config.x.version=Storefront::VERSION

Rails engines or apps that publish gems can opt into package metadata checks by setting config.gem_name and including :package_metadata in config.version_checks. Deployment and container metadata, such as Docker, Kamal, and Helm, are intentionally left for future adapter support.

Sinatra apps

Sinatra applications can use the Sinatra adapter for app-style defaults:

Semverve::Task.newdo |config|
config.adapter=:sinatraend

The Sinatra adapter stores the version in config/version.rb, uses the :simple format, infers the module name from the project directory, and checks documentation references plus configured code literals by default. It does not infer a package name from config/version.rb and does not run package metadata checks unless you opt in.

Formats

The default :module format stores MAJOR, MINOR, and PATCH constants under a Version module and exposes a top-level VERSION constant.

moduleMyGemmoduleVersionMAJOR=0MINOR=1PATCH=0module_functiondefto_a[MAJOR,MINOR,PATCH]enddefto_sto_a.join(".")endendVERSION=Version.to_send

The :simple format stores only:

moduleMyGemVERSION="1.0.0"end

Generating

Generate the default module format:

rake semverve:generate

Generate a specific version or format:

rake 'semverve:generate[1.0.0,simple]'
rake 'semverve:generate[simple]'

Generation fails if the target file already exists. To replace it:

rake 'semverve:generate[force]'

semverve:generate accepts optional tokens for version, format, and force. Token order does not matter: semantic versions set the generated version, module or simple sets the format, and force overwrites an existing version file.

rake 'semverve:generate[1.0.0,force]'
rake 'semverve:generate[simple,force]'
rake 'semverve:generate[1.0.0,simple,force]'

Bootstrapping a new gem

If your gemspec dynamically requires the generated version file, a brand-new project can fail before semverve:generate has a chance to run:

require_relative"lib/my_gem/version"

Rake loads the Rakefile before it can invoke any task. If loading the Rakefile also loads bundler/gem_tasks, Bundler evaluates the gemspec, and an unconditional require_relative can crash because lib/my_gem/version.rb does not exist yet.

Prefer guarding Bundler's gem tasks while running semverve:generate:

require"semverve/task"unlessARGV.any?{ |arg| arg.start_with?("semverve:generate")}require"bundler/gem_tasks"endSemverve::Task.new

Then generate the version file:

rake semverve:generate

After generation, you can keep the guard or switch back to your normal dynamic gemspec loading style.

Semverve's metadata inference does not evaluate the gemspec for generation; it reads the literal spec.name, so either bootstrap pattern still allows semverve:generate to infer lib/my_gem/version.rb.

Alternatively, make the gemspec tolerate the missing file during bootstrap:

version_path=File.expand_path("lib/my_gem/version",__dir__)requireversion_pathifFile.file?("#{version_path}.rb")Gem::Specification.newdo |spec|
spec.name="my_gem"spec.version=defined?(MyGem::VERSION) ? MyGem::VERSION : "0.0.0"semverveend

Incrementing

rake semverve:increment:patch
rake semverve:increment:minor
rake semverve:increment:major

Patch increments only patch. Minor increments minor and resets patch to 0. Major increments major and resets minor and patch to 0.

Successful increments print the version change:

Updating to version 2.0.2 (was 2.0.1)

Set config.bundle_lock = true to run bundle lock after increments to update your gem's version in Gemfile.lock.

Setting

Set an exact version without incrementing:

rake 'semverve:set[1.2.3]'

Successful updates print the version change:

Updating to version 1.2.3 (was 1.2.2)

Setting the current version again does not rewrite the version file:

Version is already 1.2.3

Setting a lower version prints a warning but still updates the file:

Warning: updating to version 1.9.9, which is lower than the current version 2.0.1.
Updating to version 1.9.9 (was 2.0.1)

This will also run bundle lock on success if you have config.bundle_lock = true in your config.

Checking version references, code, and metadata

Run every version check with:

rake semverve:check

This task is designed for normal CI. It uses local project files, prints parseable findings, and exits non-zero when it finds drift.

By default, gem/package projects check:

• README version references, plus any configured docs or comment files
• configured code files for safe version literals
• the gemspec version and Gemfile.lock entry

Rails adapter projects instead check README references, configured code literals, and optional Rails config metadata.

Findings are printed in parseable formats and the task exits non-zero:

README.md:12:24: version reference 1.2.2 -> 1.2.3
lib/my_gem/constants.rb:1:16: code version literal 1.2.2 -> 1.2.3
my_gem.gemspec:3:18: gemspec version 1.2.2 -> 1.2.3
Gemfile.lock:4:13: locked version 1.2.2 -> 1.2.3

Run every available fix:

rake semverve:fix

Choose which surfaces the umbrella check and fix tasks run with config.version_checks:

Semverve::Task.newdo |config|
config.version_checks=[:doc_references,:package_metadata]end

The allowed values come from Semverve's check registry. Built-in checks are :doc_references, :code_references, and :package_metadata; framework adapters can add their own checks, such as Rails' :rails_config_metadata.

Use focused tasks when you want only one surface:

rake semverve:check:references
rake semverve:fix:references
rake semverve:check:code
rake semverve:fix:code
rake semverve:check:package_metadata
rake semverve:fix:package_metadata
rake semverve:check:rails_config_metadata
rake semverve:fix:rails_config_metadata

semverve:fix:package_metadata rewrites literal gemspec versions when safe and runs bundle lock for Gemfile.lock drift. semverve:fix:rails_config_metadata rewrites safe Rails config version literals.

Pass a semantic version when you want to check or fix only that exact version in doc references and code literals:

rake 'semverve:check[1.2.2]'
rake 'semverve:fix:references[1.2.2]'

Package metadata and adapter-owned metadata checks still compare metadata to the current version. If you target the current version, check tasks list reference/code matches but fix tasks are no-ops because the text is already current.

Extension API

Semverve exposes small public objects for framework adapters and version checks. These APIs are intentionally local registration APIs; Semverve does not yet autoload third-party adapter gems.

Register a framework adapter with Semverve::Adapters.register. An adapter must expose name, defaults(configuration), and checks. It can also expose infer_package_name? to control whether app-style version files should be treated as package names.

Register a check with Semverve::VersionChecks.register, or return adapter-owned checks from an adapter's checks method. A check object should expose:

• name and task_name
• check_description, fix_description, finding_label, and fix_label
• clean_message, targetable?, and exact_target_fix_noop_notice?
• findings(configuration, current_version, include_ignored:, target_version:)
• fix(configuration, current_version, target_version:)

Checks should return Semverve::Finding objects from findings and a Semverve::FixResult from fix. Semverve::VersionMatchPolicy and Semverve::VersionLiteralRewriter are available for checks that need Semverve's standard stale-version matching or named-capture literal rewriting.

For example:

classMyConfigVersionCheck < Semverve::VersionChecks::Checkdefname=:my_config_metadatadeftask_name=:my_config_metadatadefcheck_description="Check app config metadata for version mismatches"deffix_description="Fix safe app config metadata version mismatches"deffinding_label="app config version"defclean_message="App config metadata is current."deffindings(configuration,current_version,include_ignored: false,target_version: nil)[]enddeffix(configuration,current_version,target_version: nil)Semverve::FixResult.new(changed_files: [],replacement_count: 0)endend

Version references

Version references are prose-like references to versions. These are usually in README files, docs, guides, changelogs, or comments. By default, Semverve scans README files throughout the repo:

Semverve::Task.newdo |config|
config.version_doc_reference_files=Rake::FileList["README*","**/README*"].exclude(".git/**/*","coverage/**/*","tmp/**/*","vendor/**/*")end

Add docs or Ruby comments without replacing the README defaults:

Semverve::Task.newdo |config|
config.version_doc_reference_files.append("doc/**/*.md","lib/**/*.rb")end

Replace the defaults entirely:

Semverve::Task.newdo |config|
config.version_doc_reference_files=Rake::FileList["guides/**/*.md"]end

Ruby files are scanned only in comments. Text files with .md, .markdown, .txt, .rdoc, and .adoc extensions are scanned as full text.

The default version match mode is :older, which flags only semantic versions lower than the current version in doc references and code literals:

Semverve::Task.newdo |config|
config.version_match_mode=:olderend

Use :non_current when every doc reference and code literal should match the current version:

Semverve::Task.newdo |config|
config.version_match_mode=:non_currentend

Ignore an intentional reference with semverve:ignore-version-reference on the same line or the preceding nonblank line.

This migration note intentionally mentions 1.0.0. <!-- semverve:ignore-version-reference -->

Prefer ignore markers when possible because they move with the ignored text. Configured ignores are for edge cases where a marker would render as unwanted content, such as inside a Markdown code block. They depend on line numbers, so they can drift when the file changes:

Semverve::Task.newdo |config|
config.version_reference_ignores={"README.md"=>{42=>["1.0.0"],45=>"2.0.0"}}end

Configured ignores apply to documentation references and code literals. They are exact to the version string, so other stale versions on the same line are still reported. Fix tasks leave configured ignores unchanged.

Audit ignored references by setting SEMVERVE_REPORT_IGNORED=true when running check tasks:

SEMVERVE_REPORT_IGNORED=true rake semverve:check
SEMVERVE_REPORT_IGNORED=true rake 'semverve:check[1.2.2]'

Code version literals

Code scanning is opt-in to avoid false positives. This is for arbitrary project code, not package metadata. The default is:

Semverve::Task.newdo |config|
config.version_code_reference_files=Rake::FileList[]end

Append files when you want Semverve to check safe code literals:

Semverve::Task.newdo |config|
config.version_code_reference_files.append("lib/**/*.rb")end

Or replace the list entirely:

Semverve::Task.newdo |config|
config.version_code_reference_files=Rake::FileList["lib/**/*.rb","*.gemspec"]end

Ruby code checks only obvious version assignments/constants, such as:

APP_VERSION="1.2.2"spec.version="1.2.2"

Ignore an intentional code literal with semverve:ignore-version-reference on the same line or the preceding nonblank line.

Set SEMVERVE_REPORT_IGNORED=true with semverve:check or semverve:check:code to report ignored stale literals without changing semverve:fix behavior.

The default pattern is Ruby-oriented. Semverve does not inspect file extensions or parse other languages for code literals; non-Ruby files are scanned as plain text with the same pattern. If a JavaScript, Python, or other source file uses a different version-literal shape, configure a custom pattern before adding those files.

Arbitrary string examples are ignored.

If your project has a different safe version-literal shape, provide your own pattern:

Semverve::Task.newdo |config|
config.version_code_reference_files.append("lib/**/*.rb")config.version_code_reference_pattern=/release ["'](?<version>\d+\.\d+\.\d+)["']/end

With that pattern, this line:

release"1.2.2"

matches the full release "1.2.2" text, but only 1.2.2 is captured as version. If rake semverve:fix:code is updating references to 1.2.3, the line becomes:

release"1.2.3"

The custom value must be a Regexp and must include a named capture called version. Semverve replaces only that capture when running rake semverve:fix:code, and the captured value still has to parse as a semantic version.

Package metadata

Package metadata checks are part of rake semverve:check by default for gem/package projects. They compare the current version file against:

• the resolved .gemspec version
• the matching Gemfile.lock entry, when a lockfile exists

Package metadata always requires an exact match, regardless of config.version_match_mode.

No file-list configuration is needed for these checks. Semverve resolves the gemspec from the project root and reads Gemfile.lock when one exists.

Dynamic gemspec versions work as expected:

require_relative"lib/my_gem/version"Gem::Specification.newdo |spec|
spec.name="my_gem"spec.version=MyGem::VERSIONend

Literal gemspec versions can be fixed automatically:

Gem::Specification.newdo |spec|
spec.name="my_gem"spec.version="1.2.2"end

rake semverve:fix:package_metadata updates safe literal gemspec assignments and runs bundle lock when the lockfile has drifted.

Rails config metadata

Rails config metadata checks are part of rake semverve:check when the Rails adapter is active. They scan config/application.rb, config/environments/*.rb, and config/initializers/**/*.rb for optional Rails config literals:

config.x.version="1.2.2"Rails.application.config.x.version="1.2.2"

These checks always require an exact match with the current Semverve version. rake semverve:fix:rails_config_metadata rewrites only those safe string literals. Dynamic assignments, including config.x.version = Storefront::VERSION, are considered self-managed and ignored.

Checking release readiness

Release checks are separate from rake semverve:check. They are useful in CI, but they are meant for release workflows, tag builds, or pre-publish jobs rather than every pull request.

Enable the RubyGems published-version check:

Semverve::Task.newdo |config|
config.release_checks=[:rubygems]end

Then run:

rake semverve:check:release

With :rubygems enabled, semverve:check:release asks the configured RubyGems-compatible host whether the current version already exists. If it does, the task exits non-zero with a message like:

my_gem 1.2.3 already exists on https://rubygems.org.

If all configured release checks pass, it prints:

Release checks passed.

You can also run the RubyGems check directly without changing config.release_checks:

rake semverve:check:rubygems

When the current version is not published, the focused task prints:

my_gem 1.2.3 is not published on https://rubygems.org.

Use config.rubygems_host for a private RubyGems-compatible server:

Semverve::Task.newdo |config|
config.release_checks=[:rubygems]config.rubygems_host="https://gems.example.com"end

The published-version check treats a missing gem as unpublished. It fails closed on registry errors, malformed responses, and network failures because release pipelines should not silently publish after an inconclusive preflight.

For ordinary CI, keep using the local checks:

bundle exec rake test semverve:check

For release CI, run the release check before building or pushing:

bundle exec rake semverve:check:release build

Vim

While there's no official vim support (yet), you can add the following to ~/.vim/plugin/semverve.vim.

command!-bang SemverveAudit call<SID>semverve_audit(<bang>0)
function!s:semverve_audit(report_ignored) abortletl:old_efm= &errorformattrylet &errorformat='%f:%l:%c:%m'letl:string=""if!a:report_ignoredletl:string.='SEMVERVE_REPORT_IGNORED=true 'endifletl:string.='bundle exec rake semverve:check 2>/dev/null'cexprsystemlist(l:string)
ifv:shell_error!=0copenelseccloseecho'Semverve checks passed.'endiffinallylet &errorformat=l:old_efmendtryendfunction

You can then call :SemverveAudit, which will call bundle exec rake semverve:check, and :SemverveAudit! which will call the same command with SEMVERVE_REPORT_IGNORED=true, and populate and open the quickfix list if any offenses are found.

Reporting Bugs and Requesting Features

If you have an idea or find a bug, please create an issue. Just make sure the topic doesn't already exist. Better yet, you can always submit a Pull Request.

Support this project

I love knowing when people find my work useful. Any kind of support is very much appreciated!

• ⭐️ Like the project? Star the repository!
• ❤️ Love the project? Follow me on GitHub!
• 💸 Really love it? Consider buying me a tea!