Apparent documentation bug

Support dry-types
1

Hi everybody,

I see in the 1.2.2 release notes language chiding all those low-quality irresponsible developers, of which perhaps I am one unwittingly?, for using dry-types incorrectly:

For example, building structs with Params types is considered a smell. There are dedicated tools for coercion, namely dry-schema and dry-validation. Be a responsible user of dry-types! :heart:

What is this talking about? All I see when I go to the documentation page for built-in types, including Params and Coercible, is a list of such types, with no guidance on opinions. And the dry-struct doc home page includes a Coercible in example code:

attribute :age, Types::Coercible::Integer

Please be far clearer in how to hold this tool and what problems you seek to avoid with the opinions you express. I crave understanding of your intent but it’s very hard to divine from the docs. Just on the human level, it feels pretty bad to be told to “be a responsible user” without enough context for how!

I would enjoy writing the missing passage in a PR on the relevant doc page as soon as I understand the subject matter.

I would also propose to change the practice of dropping knowledge into release notes that is not merely a summary of something the documentation makes very clear in more detail (not less). Now that documentation lives with the repo, perhaps updating documents with changes to the product can be a part of PRs, like Rails does? (Also, I remember that Rails had this same problem until the advent of the Rails Guides in version 2.2 after they had a hackfest to create them.)

Can you tell me what those release notes are telling me is unwise to do, please?

2

Thanks for the feedback, I think I’ll skip detailed explanation here because point taken. I generally agree and, of course, it wasn’t the goal to confuse people, I’ll do my best in future to prevent such confusion.
When it comes to this particular sentence the missing piece is overall understanding how things “supposed to work”. You normally don’t want to coerce data with structs because coercion inherently may fail. :params types designed to deal with user input which must be validated first using dry-schema or dry-validation. Output of dry-schema is already coerced, if you build a struct with this data its types should be :strict or :nominal rather than :params. It’s not the case for :coercible types because sometimes you expect input to be valid, just have a different type. Like reading :age from database where it’s stored as a string for some reason. Can you see the direction now?

3 Likes