railsmith 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7d121f9233f121988b7811ac803943a3d2d784ccf018e31ecb1dd681747c632
-  data.tar.gz: 0d8b3debcd71cd67bec213d7614528d61584b45f1a380b35536d5e738d848871
+  metadata.gz: 1a20ec84a09c4074cd56944e07f4ea7f14ffab15e8f9fe41d4f288ac3cc2f9ce
+  data.tar.gz: 47e886d32518f52ba779f4ce0727737653b7e719d7b266ca8a2769ab7ff2bb97
 SHA512:
-  metadata.gz: 6c82716d751374815ebe15f4fdc0763c3ff79dbf58b1985d9d8a2bbaa70e19fe010174563401fc23c811533009ad054c8d0de7130502ce80a10e2346f309d6f7
-  data.tar.gz: 97bf97006557c7fa4e6f5c19d83d47b81c48dd751bee5d66a6d812ee5072edeeaf5a3e95b8b09ec42bc3ad778e1fae3b886c93c63cbd676240cdfef96b413786
+  metadata.gz: 9c6275d694e51d5bfa1d5dd5f375af5079b0fdd96bb38252f322279df514e3e1e7945840ccf9bba14495b4e55cf7c33a4dfbfefce903402e5fe1c7345cae6984
+  data.tar.gz: 909725e026330771fd81e0b5fd0077f7f92621dc017cda6b882a7e5f276db8be589edab63857823e1c604af9b58a7a968f90f825b78652022c4a90b6f86c8285

data/CHANGELOG.md

@@ -7,6 +7,60 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+---
+
+## [1.1.0] — 2026-03-30
+
+### Added
+
+- Appraisal-style gemfiles for CI and local testing: `gemfiles/rails_7.gemfile` and `gemfiles/rails_8.gemfile` (with lockfiles), pinning `activerecord` / `railties` to Rails 7.x and 8.x respectively.
+- `--namespace` flag on `railsmith:model_service` and `railsmith:operation` generators.
+  Wraps the generated class in the given modules (e.g. `--namespace=Billing::Services`).
+  When a namespace is provided on `model_service`, `domain` is automatically set from its first segment.
+  Pass `--namespace=Operations` explicitly to match the pre-1.1 default layout.
+- `Railsmith::Context` — canonical context value object (replaces `Railsmith::DomainContext` for new code).
+  Accepts `domain:` (preferred) and arbitrary top-level keyword args (`actor_id:`, `request_id:`, etc.) without a nested `:meta` hash.
+  `#[]` accessor, `#blank_domain?`, `#to_h` (backward-compatible shape: `{ current_domain: ..., **extras }`).
+- `Context#request_id` — auto-generated UUID (`SecureRandom.uuid`) when no `request_id:` is supplied; explicit values always win (e.g. `X-Request-Id`).
+- `Context.build(value)` — coerces context-like values into a `Context` (`Context` as-is, hash with `:domain` / `:current_domain`, or `nil`/`{}` for a minimal context with auto `request_id`).
+- `Railsmith::Context.current` and `Railsmith::Context.with(**kwargs, &block)` — thread-local context for the request scope; nested blocks restore the previous value.
+- `domain` DSL on `BaseService` subclasses — preferred alias for `service_domain` (aligned with `Context`’s `domain:` kwarg).
+- `find` and `list` actions on model-backed services — `find` returns `Result.success(value: record)` or `not_found`; `list` defaults to `model_class.all` (override for filtering).
+
+### Changed
+
+- `railsmith:model_service MODEL` — default output is `app/services/<model>_service.rb` with **no module wrapper** (was `app/services/operations/<model>_service.rb` in `module Operations`). Existing code is unaffected.
+- `railsmith:operation NAME` — default hierarchy is `<Domain>::…::<Operation>` without an interstitial `Operations` module (was `.../operations/...` on disk and in module nesting). Use `--namespace=Operations` for the old layout.
+- `Railsmith::BaseService::ContextPropagation` — renamed from `DomainContextPropagation`; reads both `:current_domain` and `:domain` for compatibility.
+- `context:` on `BaseService.call` is **optional**; omitting it, or passing `nil`/`{}`, yields a real `Context` with an auto `request_id` (no `ArgumentError`).
+- `BaseService.call` context resolution: explicit `context:` > thread-local `Context.current` > auto-built empty context.
+- **Ruby**: minimum supported version is **>= 3.1.0** (was >= 3.2.0). RuboCop `TargetRubyVersion` is aligned to 3.1.
+- `Railsmith::Context` implementation: `.with` / `.build` use `thread_context_from` and `build_from_hash` as `private_class_method`s; `#[]` uses `%i[current_domain domain]` for domain lookup (behavior unchanged).
+- Packaged gem file list: `gemfiles/`, `.ruby-version`, and `.tool-versions` excluded from the gem tarball.
+
+### Deprecated
+
+- `Railsmith::DomainContext` — deprecation warning on `.new`; removed in a future major release. Use `Railsmith::Context`.
+- `current_domain:` on `Context.new` — use `domain:` (warning when used).
+- `service_domain` on `BaseService` — use `domain` (warning when used); removed in a future major release.
+
+### Fixed
+
+- Removed obsolete `Style/ArgumentsForwarding` RuboCop disables in bulk helpers (`bulk_actions`, `bulk_execution`).
+- `activerecord` is an explicit runtime dependency (`>= 7.0, < 9.0`); avoids opaque `NoMethodError` when CRUD/bulk run outside a full Rails load.
+- Root `Gemfile` pins `connection_pool`, `nokogiri`, `erb`, and `zeitwerk` under `RUBY_VERSION < "3.2"`, matching `gemfiles/rails_7.gemfile`, so Ruby 3.1 resolves without forcing `BUNDLE_GEMFILE`.
+- `railsmith:operation` — `initialize` uses `Railsmith::Context.build(context)` instead of `deep_dup` on context; frozen `Context` instances work; generated stub uses `context[:domain]` only.
+- `railsmith:model_service` — domain mode no longer emits `_service.rb` when the model name omits the domain prefix; generator comments reference `domain`, not `service_domain`.
+
+### Development
+
+- GitHub Actions **CI**: lint (RuboCop, Ruby 3.3); test matrix Ruby 3.1–3.3 × Rails 7/8 gemfiles (Ruby 3.1 excluded with Rails 8). `permissions: contents: read`, `fail-fast: false`, `ruby/setup-ruby` `gemfile:` for installs.
+- `railsmith:model_service` generator: file-level `Metrics/ClassLength` RuboCop disable/enable around `ModelServiceGenerator` only.
+
+---
+
 ## [1.0.0] — 2026-03-29
 
 First stable release. Public DSL and result contract are now frozen.
@@ -62,3 +116,7 @@ First stable release. Public DSL and result contract are now frozen.
 ## [0.1.0] — pre-release
 
 Internal bootstrap release. Gem skeleton, CI baseline, and initial service scaffolding. Not intended for production use.
+
+[Unreleased]: https://github.com/samaswin/railsmith/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/samaswin/railsmith/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/samaswin/railsmith/releases/tag/v1.0.0

data/MIGRATION.md

@@ -1,5 +1,275 @@
 # Migration Guide
 
+## Upgrading from 1.0.0 to 1.1.0
+
+### Ruby >= 3.1 (non-breaking)
+
+Railsmith **1.0.0** declared `required_ruby_version >= 3.2.0`. **1.1.0** lowers the minimum to **>= 3.1.0** so apps on Ruby 3.1 can depend on the gem without changing service code.
+
+If you already run Ruby 3.2 or newer, no action is required.
+
+---
+
+### `DomainContext` → `Context` (non-breaking, deprecation warning)
+
+
+`Railsmith::DomainContext` is deprecated in favour of `Railsmith::Context`. The old class still works but prints a deprecation warning on every `.new` call. It will be removed in the next major release.
+
+#### New API at a glance
+
+```ruby
+# Before (1.0.0)
+Railsmith::DomainContext.new(
+  current_domain: :billing,
+  meta: { request_id: "req-abc", actor_id: current_user.id }
+)
+
+# After (1.1.0)
+Railsmith::Context.new(
+  domain: :billing,
+  actor_id: current_user.id   # top-level, no :meta wrapper
+)
+```
+
+Key differences:
+
+| | `DomainContext` (old) | `Context` (new) |
+|---|---|---|
+| Class | `Railsmith::DomainContext` | `Railsmith::Context` |
+| Domain kwarg | `current_domain:` | `domain:` |
+| Extra fields | nested under `meta:` | top-level kwargs |
+| `to_h` shape | `{ current_domain:, **meta }` | same (unchanged) |
+
+#### Migration steps
+
+1. **Find all `DomainContext` usages:**
+   ```
+   grep -r "DomainContext" app/ spec/
+   ```
+
+2. **Replace the class name and kwargs:**
+   ```ruby
+   # Before
+   ctx = Railsmith::DomainContext.new(current_domain: :billing, meta: { request_id: "r1", actor_id: 42 })
+
+   # After
+   ctx = Railsmith::Context.new(domain: :billing, request_id: "r1", actor_id: 42)
+   ```
+
+3. **If you read `ctx.meta` directly**, switch to individual readers:
+   ```ruby
+   ctx.meta[:actor_id]    # before
+   ctx[:actor_id]         # after
+   ```
+
+4. **No changes needed at the call site.** `to_h` output is identical — services reading `context[:current_domain]` continue to work without modification.
+
+#### Passing a context hash directly (unchanged)
+
+Services that receive a plain hash (e.g. `context: { current_domain: :billing, actor_id: 42 }`) are unaffected. The hash shape is preserved by `Context#to_h`.
+
+---
+
+### Generator defaults — no forced namespace (non-breaking)
+
+The `railsmith:model_service` and `railsmith:operation` generators no longer wrap generated classes in an `Operations::` module by default.
+
+#### model_service generator
+
+| | 1.0.0 default | 1.1.0 default |
+|---|---|---|
+| Command | `rails g railsmith:model_service User` | same |
+| Output file | `app/services/operations/user_service.rb` | `app/services/user_service.rb` |
+| Module wrapper | `module Operations` | none |
+| Call site | `Operations::UserService.call(...)` | `UserService.call(...)` |
+
+**Existing services are not broken** — any service already generated under `Operations::` continues to work without changes. The change only affects newly generated files.
+
+To generate with an explicit namespace (e.g. when you want domain grouping):
+
+```bash
+rails generate railsmith:model_service Invoice --namespace=Billing::Services
+# => app/services/billing/services/invoice_service.rb
+# => module Billing; module Services; class InvoiceService
+# => domain :billing  (auto-added from first segment)
+```
+
+To preserve the old `Operations::` default in a project that still wants it, pass `--namespace=Operations`:
+
+```bash
+rails generate railsmith:model_service User --namespace=Operations
+# => app/services/operations/user_service.rb  (same as before)
+```
+
+#### operation generator
+
+| | 1.0.0 default | 1.1.0 default |
+|---|---|---|
+| Command | `rails g railsmith:operation Billing::Invoices::Create` | same |
+| Output file | `app/domains/billing/operations/invoices/create.rb` | `app/domains/billing/invoices/create.rb` |
+| Module hierarchy | `Billing::Operations::Invoices::Create` | `Billing::Invoices::Create` |
+
+**Existing operations are not broken** — files already under `.../operations/...` are unaffected.
+
+To restore the old `Operations` interstitial module:
+
+```bash
+rails generate railsmith:operation Billing::Invoices::Create --namespace=Operations
+# => app/domains/billing/operations/invoices/create.rb  (same as before)
+```
+
+---
+
+### Auto-generated `request_id` (non-breaking)
+
+`Railsmith::Context` now assigns a UUID `request_id` automatically at construction when one is not provided.
+
+```ruby
+ctx = Railsmith::Context.new(domain: :billing, actor_id: 42)
+ctx.request_id  # => "550e8400-e29b-41d4-a716-446655440000"  (auto-generated)
+ctx.to_h        # => { current_domain: :billing, actor_id: 42, request_id: "550e8400-..." }
+```
+
+To forward an existing request ID (e.g. from an incoming HTTP header), pass it explicitly — it is never overwritten:
+
+```ruby
+ctx = Railsmith::Context.new(domain: :web, request_id: request.headers["X-Request-Id"])
+ctx.request_id  # => whatever the header contained
+```
+
+**No migration required.** All existing code that already passes `request_id:` continues to work unchanged. Code that omitted it now gets a UUID instead of `nil` in `to_h` — this is the intended behaviour.
+
+If you have specs that assert `Context#to_h` equals an exact hash without a `request_id` key, update them to use `include(...)` or pass an explicit `request_id:` to fix the value:
+
+```ruby
+# Before (will fail — to_h now always includes request_id)
+expect(ctx.to_h).to eq(current_domain: :billing, actor_id: 42)
+
+# After — option A: assert on the keys you care about
+expect(ctx.to_h).to include(current_domain: :billing, actor_id: 42)
+
+# After — option B: fix the request_id to make equality deterministic
+ctx = Railsmith::Context.new(domain: :billing, actor_id: 42, request_id: "r1")
+expect(ctx.to_h).to eq(current_domain: :billing, actor_id: 42, request_id: "r1")
+```
+
+---
+
+### `context:` is now optional at the call site (non-breaking)
+
+`BaseService.call` no longer requires `context:`. Omitting it, passing `nil`, or passing `{}` all produce a valid `Context` with an auto-generated `request_id`.
+
+```ruby
+# All of these are equivalent and valid in 1.1.0
+UserService.call(action: :create, params: { attributes: { name: "Alice" } })
+UserService.call(action: :create, params: { ... }, context: {})
+UserService.call(action: :create, params: { ... }, context: nil)
+```
+
+If you previously passed `context: {}` as a no-op placeholder, you can remove it — the behaviour is identical.
+
+When you do pass a context value, `Context.build` handles coercion:
+
+| Value passed | Result |
+|---|---|
+| A `Railsmith::Context` | used as-is |
+| A hash with `:domain` or `:current_domain` | wrapped in `Context.new(**hash)` |
+| `nil` or `{}` | new `Context` with auto `request_id` |
+
+**No migration required.** Existing code that passes a full context is unaffected.
+
+---
+
+### New read actions: `find` and `list` (non-breaking, additive)
+
+Two new CRUD actions are available on all model-backed services.
+
+```ruby
+# Find a single record by ID
+result = UserService.call(action: :find, params: { id: 1 })
+result.value  # => <User id=1>
+
+# List all records (override to filter)
+result = UserService.call(action: :list, params: {})
+result.value  # => [<User>, ...]
+```
+
+Default `list` calls `model_class.all`. Override it when you need filtering:
+
+```ruby
+class UserService < Railsmith::BaseService
+  model User
+
+  def list
+    users = User.where(active: params[:active]).order(:name)
+    Result.success(value: users)
+  end
+end
+```
+
+**No migration required.** These are new methods; existing overrides are unaffected. If you had a custom `find` or `list` method that returns a different shape, it will shadow the default — check your override's return value matches `Result.success`/`Result.failure`.
+
+---
+
+### Thread-local context propagation (opt-in, non-breaking)
+
+`Railsmith::Context.with(...)` sets a thread-local context for the duration of a block. Services automatically inherit it when no explicit `context:` is passed.
+
+```ruby
+# Set once at the edge (e.g. ApplicationController)
+around_action do |_, block|
+  Railsmith::Context.with(domain: :web, actor_id: current_user&.id) { block.call }
+end
+
+# Services pick it up automatically — no need to thread it through every call
+UserService.call(action: :create, params: { ... })
+```
+
+Resolution order: **explicit `context:` arg > `Context.current` > auto-built empty context**.
+
+Explicit `context:` always wins, so existing code that passes context explicitly is completely unaffected.
+
+`Context.current` returns the current thread-local `Context` or `nil`. `Context.with` restores the previous value after the block, making it safe for nested calls and concurrent requests.
+
+**No migration required.** This is fully opt-in.
+
+---
+
+### `service_domain` → `domain` DSL (non-breaking, deprecation warning)
+
+The `service_domain` class macro is deprecated in favour of `domain`.
+
+```ruby
+# Before (1.0.0)
+class InvoiceService < Railsmith::BaseService
+  model Invoice
+  service_domain :billing
+end
+
+# After (1.1.0)
+class InvoiceService < Railsmith::BaseService
+  model Invoice
+  domain :billing
+end
+```
+
+`service_domain` still works but emits a deprecation warning. It will be removed in the next major release.
+
+#### Migration steps
+
+```
+grep -r "service_domain" app/
+```
+
+Replace each occurrence:
+
+```ruby
+service_domain :billing   # before
+domain :billing           # after
+```
+
+---
+
 ## Upgrading from 0.x (pre-release) to 1.0.0
 
 Railsmith 1.0.0 is the first stable release. If you were using the 0.x development version, the changes below are required before upgrading.
@@ -13,7 +283,7 @@ Railsmith 1.0.0 is the first stable release. If you were using the 0.x developme
 | Ruby | >= 3.2.0 | >= 3.2.0 |
 | Rails | 7.0–8.x | 7.0–8.x |
 
-No changes to minimum runtime requirements.
+No other changes to minimum runtime requirements at the 1.0.0 release. (Ruby **3.1** is supported starting in **1.1.0**; see the section above.)
 
 ---
 
@@ -78,11 +348,11 @@ The `on_cross_domain_violation` config callback still fires and is the recommend
 
 Domain-scoped services are now always generated under `app/domains/<domain>/services/`. If you used the generator during 0.x development and accepted a different default path, move the files and update `require` paths accordingly.
 
-| Generator | Output path (1.0.0) |
-|-----------|---------------------|
-| `railsmith:model_service User` | `app/services/operations/user_service.rb` |
-| `railsmith:model_service Billing::Invoice --domain=Billing` | `app/domains/billing/services/invoice_service.rb` |
-| `railsmith:operation Billing::Invoices::Create` | `app/domains/billing/operations/invoices/create.rb` |
+| Generator | Output path (1.0.0) | Output path (1.1.0) |
+|-----------|---------------------|---------------------|
+| `railsmith:model_service User` | `app/services/operations/user_service.rb` | `app/services/user_service.rb` |
+| `railsmith:model_service Billing::Invoice --domain=Billing` | `app/domains/billing/services/invoice_service.rb` | `app/domains/billing/services/invoice_service.rb` |
+| `railsmith:operation Billing::Invoices::Create` | `app/domains/billing/operations/invoices/create.rb` | `app/domains/billing/invoices/create.rb` |
 
 ---
 

data/README.md

@@ -2,7 +2,7 @@
 
 Railsmith is a service-layer gem for Rails. It standardizes domain-oriented service boundaries with sensible defaults for CRUD operations, bulk operations, result handling, and cross-domain enforcement.
 
-**Requirements**: Ruby >= 3.2.0, Rails 7.0–8.x
+**Requirements**: Ruby >= 3.1.0, Rails 7.0–8.x
 
 ---
 
@@ -33,10 +33,9 @@ rails generate railsmith:model_service User
 Call it:
 
 ```ruby
-result = Operations::UserService.call(
+result = UserService.call(
   action: :create,
-  params: { attributes: { name: "Alice", email: "alice@example.com" } },
-  context: {}
+  params: { attributes: { name: "Alice", email: "alice@example.com" } }
 )
 
 if result.success?
@@ -79,31 +78,29 @@ result.error.to_h      # => { code: "not_found", message: "User not found", deta
 |---------|--------|
 | `rails g railsmith:install` | Initializer + service directories |
 | `rails g railsmith:domain Billing` | `app/domains/billing.rb` + subdirectories |
-| `rails g railsmith:model_service User` | `app/services/operations/user_service.rb` |
+| `rails g railsmith:model_service User` | `app/services/user_service.rb` |
 | `rails g railsmith:model_service Billing::Invoice --domain=Billing` | `app/domains/billing/services/invoice_service.rb` |
-| `rails g railsmith:operation Billing::Invoices::Create` | `app/domains/billing/operations/invoices/create.rb` |
+| `rails g railsmith:operation Billing::Invoices::Create` | `app/domains/billing/invoices/create.rb` |
 
 ---
 
 ## CRUD Actions
 
-Services that declare a `model` inherit `create`, `update`, and `destroy` with automatic exception mapping:
+Services that declare a `model` inherit `create`, `update`, `destroy`, `find`, and `list` with automatic exception mapping:
 
 ```ruby
-module Operations
-  class UserService < Railsmith::BaseService
-    model(User)
-  end
+class UserService < Railsmith::BaseService
+  model(User)
 end
 
-# create
-Operations::UserService.call(action: :create, params: { attributes: { email: "a@b.com" } }, context: {})
+# create (context: is optional from 1.1 onward)
+UserService.call(action: :create, params: { attributes: { email: "a@b.com" } })
 
 # update
-Operations::UserService.call(action: :update, params: { id: 1, attributes: { email: "new@b.com" } }, context: {})
+UserService.call(action: :update, params: { id: 1, attributes: { email: "new@b.com" } })
 
 # destroy
-Operations::UserService.call(action: :destroy, params: { id: 1 }, context: {})
+UserService.call(action: :destroy, params: { id: 1 })
 ```
 
 Common ActiveRecord exceptions (`RecordNotFound`, `RecordInvalid`, `RecordNotUnique`) are caught and converted to structured failure results automatically.
@@ -114,27 +111,24 @@ Common ActiveRecord exceptions (`RecordNotFound`, `RecordInvalid`, `RecordNotUni
 
 ```ruby
 # bulk_create
-Operations::UserService.call(
+UserService.call(
   action: :bulk_create,
   params: {
     items: [{ name: "Alice", email: "a@b.com" }, { name: "Bob", email: "b@b.com" }],
     transaction_mode: :best_effort  # or :all_or_nothing
-  },
-  context: {}
+  }
 )
 
 # bulk_update
-Operations::UserService.call(
+UserService.call(
   action: :bulk_update,
-  params: { items: [{ id: 1, attributes: { name: "Alice Smith" } }] },
-  context: {}
+  params: { items: [{ id: 1, attributes: { name: "Alice Smith" } }] }
 )
 
 # bulk_destroy
-Operations::UserService.call(
+UserService.call(
   action: :bulk_destroy,
-  params: { items: [1, 2, 3] },
-  context: {}
+  params: { items: [1, 2, 3] }
 )
 ```
 
@@ -156,24 +150,21 @@ module Billing
   module Services
     class InvoiceService < Railsmith::BaseService
       model(Billing::Invoice)
-      service_domain :billing
+      domain :billing
     end
   end
 end
 ```
 
-Pass context on every call:
+Pass context when you need domain or tracing data (`context:` is optional; omit it to use thread-local `Context.current` or an auto-built context):
 
 ```ruby
-ctx = Railsmith::DomainContext.new(
-  current_domain: :billing,
-  meta: { request_id: "req-abc" }
-).to_h
+ctx = Railsmith::Context.new(domain: :billing, request_id: "req-abc")
 
 Billing::Services::InvoiceService.call(action: :create, params: { ... }, context: ctx)
 ```
 
-When `current_domain` in the context differs from a service's declared `service_domain`, Railsmith emits a `cross_domain.warning.railsmith` instrumentation event.
+When the context domain differs from a service's declared `domain`, Railsmith emits a `cross_domain.warning.railsmith` instrumentation event.
 
 Configure enforcement in `config/initializers/railsmith.rb`:
 
@@ -225,6 +216,8 @@ See [Migration](MIGRATION.md#embedding-architecture-checks-from-ruby) for option
 - [Quickstart](docs/quickstart.md) — install, generate, first call
 - [Cookbook](docs/cookbook.md) — CRUD, bulk, domain context, error mapping, observability
 - [Legacy Adoption Guide](docs/legacy-adoption.md) — incremental migration strategy
+- [Migration](MIGRATION.md) — upgrading from 1.0.x to 1.1.x (and earlier releases)
+- [Changelog](CHANGELOG.md)
 
 ---
 
@@ -236,8 +229,19 @@ bundle exec rake spec   # run tests
 bin/console     # interactive prompt
 ```
 
+CI runs the suite against Rails 7 and Rails 8 using [`gemfiles/rails_7.gemfile`](gemfiles/rails_7.gemfile) and [`gemfiles/rails_8.gemfile`](gemfiles/rails_8.gemfile) (Ruby 3.1–3.3; Rails 8 is not paired with Ruby 3.1 in CI). To reproduce a matrix cell locally:
+
+```bash
+BUNDLE_GEMFILE=gemfiles/rails_7.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7.gemfile bundle exec rspec
+```
+
 To install locally: `bundle exec rake install`.
 
+### Releasing
+
+With `lib/railsmith/version.rb` and `CHANGELOG.md` updated and committed, run `bundle exec rake release` to tag `v` + version, build the gem, and push to RubyGems (requires `gem push` credentials and a clean git state). To publish manually: `gem build railsmith.gemspec` then `gem push railsmith-X.Y.Z.gem`.
+
 ---
 
 ## Contributing