5.7.1: README refactor, pt-BR translation, no-breaking-changes alert#148
Merged
Conversation
Documentation-only release: restructures the English README for clearer onboarding and reference (see the README change in the next commit) and documents the previously-undocumented `Micro::Case.config.set_activemodel_validation_errors_failure` config option. No API or behavior changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Add a 30-second taste snippet under the badges and a refreshed "What you get" value-prop that surfaces the 5.3-5.7 features (typed results, contracts, transactions, pattern matching, exception safety). - Promote result contracts and pattern matching out of nested Result subsections to first-class subsections under "Working with results". - Group composition under a new "Composing use cases" umbrella with three peers: Flows, Internal steps (Result#then chains), Transactions. - Frame `accept:` / `reject:` as the default attribute-validation story and `u-case/with_activemodel_validation` as the opt-in Rails layer. - Condense the Benchmarks section into a single comparison table plus short subsections for running benchmarks and disabling runtime checks. - Add an inline end-to-end sign-up flow under Examples that shows contracts + a transactional flow + result hooks together. - Uniformly declarative heading style (FAQ-style "Is it possible...?" / "How to...?" titles removed) and thinned "Back to Top" links from ~20 occurrences to 7. - Document `Micro::Case.config.set_activemodel_validation_errors_failure` (previously orphan-referenced) and `Kind.of?` (used in several examples without explanation). - Add a note that contracts, hooks, and pattern matching are independent features: contracts fire at Success(...) / Failure(...) call time; callers consume the resulting Result normally. No API or behavior changes. The pt-BR README will be brought in lockstep in a follow-up commit before release. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Restore the deeper ToC nesting that was thinned during the refactor: Safe flows, `Result#on_exception`, Opting out of Safe; disable_auto_validation, Kind::Validator; the four Flows sub-headings; all seven Internal steps sub-headings; all six Transactions sub-headings; Performance and Examples subsections. The ToC now covers every L4 / L5 anchor. - Re-align the Pattern matching key table and the two Performance comparison tables (trailing-whitespace fixes from the formatter). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…anges alert Every math-based example in the English README is replaced with a realistic, non-math use case that exercises the same API surface: - 30-second taste: `Multiply` → `Slugify` (blog post title → slug) - Defining basics: `Multiply` → `ValidateEmail` - Strict mode: `Double(numbers)` → `FormatGreeting(name, time_of_day)` - Safe + on_exception: `Divide` / ZeroDivisionError → `ParseJsonPayload` / `JSON::ParserError` - Default result types: `Divide` (:ok/:error/:exception) → `FetchUser(id)` (User.find rescuing not-found) - Custom result types: `Multiply :invalid_data` → `MergeTags(primary, secondary) :invalid_input` (symmetric Array type check) - Result contracts: `Divide` contract → `PublishPost(post)` with :already_published / :missing_content; `Wrong` → `CreateComment` - Result hooks / multi-call / decomposition: `Double(number)` with :invalid / :lte_zero → `ChangePassword(user, new_password)` with :weak / :reused - `Result#then`: `ForbidNegativeNumber` + `Add3` → `FindActiveUser` + `GenerateInviteToken`; `Add` block-form → `FindUser` - ActiveModel section: `Multiply` + validates presence/numericality → `CreatePost` + validates presence/length; `disable_auto_validation` variant becomes `CountPosts` - Flows `Steps` module: `ConvertTextToNumbers` / `Add2` / `Double` / `Square` → `ParseTags` / `Downcase` / `StripHashPrefix` / `RemoveDuplicates` (tag-normalization pipeline) - Self-referential flow: `ConvertTextToNumber` + `Double` + `ConvertNumberToText` → `ParseTagsString` + `CleanTags` + `JoinTagsArray` - Internal steps (`Result#then` chains): `SumHalf` + `DoSomeSum` math chain → `CapitalizeTitle` + `CreateBlogPost` with `.then(:strip_title).then(:slugify, separator: '-').then(CapitalizeTitle)` Also adds a GitHub `[!IMPORTANT]` alert at the top of the README surfacing the **no-breaking-changes** policy (per #131 (comment)): `u-case` will not introduce breaking changes; redesigns belong in `solid-process`. CHANGELOG entry updated accordingly (and date bumped to 2026-05-26). No API or behavior changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Alert headline tightened from "No breaking changes — ever" to "No breaking API changes — ever" and a new paragraph clarifies that major version bumps will happen — but only to signal that a Ruby or Rails version was dropped from the supported matrix (SemVer dependency-floor change), not as an API change. - Reframed the solid-process parenthetical: "the u-case successor" → "a redesign that applies what we've learned since u-case was created". Honest about coexistence; positions solid-process as informed by hindsight rather than a replacement. - Added a new "Inspectable execution" bullet to What you get, highlighting result.transitions as a first-class observability feature: every flow records each step's input, output, and accessible attributes for debugging, logging, and audit trails. - Highlighted the Transactions bullet with a ⚡ marker and expanded its description to spell out the headline capabilities (multi-DB support, global default callback, inline transaction block helper). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…tart
- New top-level section between Examples and Development covering two
patterns the README has not previously documented:
- **Nested attributes (block form)** — `attribute :customer do … end`
with a CreateOrder example showing inner accept: validations
rolling up into the parent's :invalid_attributes failure.
- **Accepting another attribute class** — `accept: Address` (with
`Address = Micro::Attributes.new { … }`) auto-coercing incoming
hashes into instances, demonstrated via CreateProfile.
Closes with a pointer to the u-attributes README for the rest of
the feature set (defaults, allow_nil, validators).
- ToC entry for the new section + its two subsections.
- `[!TIP]` callout right under the 30-second taste teasing the
nested-attribute capability and linking forward to the new section,
so first-time readers see the feature exists without bloating the
taste itself.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Full pt-BR retranslation of the post-refactor English README so the two are now in lockstep. Every section, alert, code example, and cross-reference is mirrored, with Portuguese-slug anchors throughout. Code identifiers stay in English (class/variable names) while comments and prose are translated. The bilingual link at the top of the pt-BR now points back to the English version. - Promotes pattern matching out of an aside inside the Typed-results bullet into its own dedicated bullet in both READMEs, right under Typed results. The new bullet calls out the deconstruct / deconstruct_keys machinery and lists the keys available for case/in matching. - CHANGELOG entry updated: notes that both READMEs are now in lockstep, drops the "pt-BR will follow in a follow-up commit" caveat, and adds coverage of the new "Going further with u-attributes" section in both languages. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Both "Nested attributes (block form)" and "Accepting another attribute class" in the Going further section require u-attributes >= 3.1 (the gem itself supports >= 2.8, < 4.0, but the nested-attribute machinery landed in u-attributes 3.1). Flagged inline at the section intro so the note covers both subsections without duplication. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
English fixes:
- Typed results: now lists the three discriminants
(success?/failure?, :type symbol, data hash) so the bullet earns
the word "Typed".
- Transactions on demand: fixed "use case or a whole flow or inline
steps" three-noun or...or grammar; now reads as a clean serial-comma
list ending with "an inline Result#then chain", mirroring the
Composable three ways vocabulary.
- Fast: restored the specific claim ("second-fastest after Dry::Monads
in the benchmarks, with no global state") — the lone "See the
benchmarks" gave readers no value-prop.
- Immutable & callback-free: added "lifecycle" to disambiguate the
rejected before/after/around callbacks from u-case's result hooks
(on_success/on_failure/on_exception).
pt-BR brought fully in lockstep with the new English: the four bullets
above were translated, and the previously-verbose Pattern matching,
Contratos de resultado, and Transações sob demanda bullets were
tightened to match the user's recent English tightening.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Several bullets reduced to one-liners with short link-based pointers to the deep dives. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Both READMEs (EN + pt-BR) now use modern Ruby syntax across every
example:
- **Hash value omission** (Ruby 3.1+): `{ user: user, email: email }`
becomes `{ user:, email: }` wherever the value is a local variable
or attribute reader with the same name as the key. Same shorthand
applied to method-call kwargs (e.g. `User.create(name:, email:)`,
`Post.create!(title:, body:)`, `User.find_by(email:)`).
- **`it` block parameter** (Ruby 3.4+): single-argument blocks that
threaded `|r|` / `|c|` through purely to dereference it now use the
implicit `it`. Examples:
.on_success { puts it[:slug] }
.on_failure(:invalid_attributes) { warn it[:errors] }
.then { it.success? ? it[:user].id : nil }
Micro::Case.config { it.disable_runtime_checks = true }
Two-argument blocks (e.g. `|_r, use_case|`) and long config blocks
with many references (`Micro::Case.config do |config| ... end`)
keep explicit parameters for readability.
- Unused single-arg blocks (`|_e|`, `|_r|`) had the parameter dropped
entirely where Ruby allows it — e.g.
`.on_exception(JSON::ParserError) { puts 'Malformed JSON.' }` and
the multi-call counter example (`.on_success { calls += 1 }`).
Verified the syntax against Ruby 4.0.1 (which is now the project's
active version) end-to-end against an actual `Micro::Case` use case,
including `on_success`, `on_failure(:type)`, `on_failure` without a
filter, `on_exception(SomeError)`, and `Result#then { ... }`. All
hooks pass the result to `it` correctly.
The kind gem dependency note keeps its prose `{ |v| v.is_a?(SomeClass) }`
example since it's documentation showing equivalence rather than a
runnable example.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Restructures the section that opens the README, mirroring the pattern
u-attributes uses:
- Renames "A 30-second taste" → "Quick start".
- The first code block still leads with `Slugify` (the existing example)
but now also folds in the case/in pattern-matching demo as a second
half of the same block, separated by an inline comment header.
- A new "Need a structured input?" section under it shows `CreateOrder`
with an `attribute :customer do ... end` block, a custom `accept:`
predicate, and a `transaction do ... end` block that demonstrates
the inline transaction helper with mixed reads/writes.
- The closing "Need atomic, multi-step work?" section keeps the
side-by-side `Micro::Cases.flow(transaction: true, ...)` and inline
`transaction { ... }` shapes, now using a more substantive
`CreateUserWithProfile` example with attribute-level accept:
validation and a `create_user` helper that returns a Result.
- Closing pointer routes readers to "Composing use cases" and "Going
further with u-attributes" for the deep dive.
pt-BR is brought in lockstep with the same structure (translated prose,
identical code).
CHANGELOG bullet for 5.7.1 updated to describe the Quick start instead
of the old 30-second-taste snippet, and the companion bullet about
"Going further with u-attributes" now says the Quick start's closing
pointer routes there (instead of the removed [!TIP] callout).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ode block Reads as a framing statement under the section heading instead of a recap after the code. The reader gets the mental model first, then sees the code that embodies it. Applied to both READMEs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Drops the mention of "inline Result#then chain" (already covered implicitly by "flow") and moves the link to the phrase that names the underlying primitive — ActiveRecord transaction — instead of the generic "flow". Applied to both READMEs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Adds assets/ucase_brand_v2.png and assets/ucase_logo_v2.png. - Removes the v1 counterparts (assets/ucase_brand_v1.png, assets/ucase_logo_v1.png). - Repoints the README header in both languages to ucase_logo_v2.png. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation-only
5.7.1release. No API or behavior changes — every public API, runtime contract, and dependency floor is identical to5.7.0.Top changes (commit-by-commit on the branch):
4901449Bump to 5.7.1 — version bump + initialCHANGELOGentry.7911912Restructure README — declarative headings throughout, new 30-second taste, refreshed "What you get" value-prop, promoted result contracts / pattern matching / internal steps / transactions out of their nested homes, grouped flows + internal steps + transactions under a new "Composing use cases" umbrella, condensed benchmarks, new inline end-to-end Examples flow. Documented the previously-orphanedMicro::Case.config.set_activemodel_validation_errors_failureconfig option.0cf60f7ToC + table alignment — fleshed out the deeper-nested ToC entries (Safe subsections, Flow children, Internal-steps subsections, all six Transaction subsections, Performance and Examples children) and fixed alignment in the Pattern-matching and Performance tables.e3bf6a8Rewrite math examples — every math-based example class is now a realistic Rails idiom:Slugify,ValidateEmail,FormatGreeting,ParseJsonPayload,FetchUser,MergeTags,PublishPost,CreateComment,ChangePassword,FindActiveUser+GenerateInviteToken+FindUser,CreatePost+CountPosts, a tag-normalizationStepsmodule,CleanTags+ParseTagsString+JoinTagsArray, andCreateBlogPost+CapitalizeTitle. Same teaching points; noMultiply/Divide/Double/Add/Square/Add2/Add3/SumHalf/DoSomeSum/ForbidNegativeNumber/ConvertTextToNumber(s)left. Adds a top-of-README[!IMPORTANT]alert surfacing the no-breaking-changes policy from issue #131.0a3fa15Refine alert + new bullet — alert headline tightened to No breaking API changes — ever and clarifies that major version bumps signal only a Ruby/Rails support-matrix drop (SemVer dependency-floor change). Reframed solid-process as a redesign that applies what we've learned (instead of successor). Added a new Inspectable execution bullet to What you get, surfacingresult.transitionsas a first-class observability feature, and highlighted ⚡ Transactions on demand with an expanded description.baa533cGoing further with u-attributes — new top-level section between Examples and Development covering twou-attributespatterns this README hadn't shown before: Nested attributes (block form) viaattribute :customer do … end(withCreateOrderexample) and Accepting another attribute class viaaccept: Address(withCreateProfileexample). A[!TIP]callout under the 30-second taste links forward to the new section.1c31fe2Translate to pt-BR — full retranslation of the post-refactor README so EN + pt-BR are now in lockstep. Portuguese-slug anchors throughout. Pattern matching also gets its own bullet in What you get / Recursos (instead of being a passing reference under Typed results).217ea61u-attributes >= 3.1 note — inline note at the Going further with u-attributes section intro flagging that both nested-attribute patterns requireu-attributes >= 3.1(the top-level Compatibility floor of>= 2.8still applies to using the gem itself).Stats:
2178 → 1588lines.2198 → 1589lines, retranslated against the new English structure.CHANGELOGentry covers all of the above underAdded+Changed.Test plan
5.7.1for the v5.x row.CHANGELOG.mdopens cleanly with the new## [5.7.1] - 2026-05-26entry at the top, compare link at the bottom.bundle exec rake testandbundle exec rake matrixare clean (docs-only change but worth confirming nothing inlib/micro/case/version.rbslipped).🤖 Generated with Claude Code