"But wait," the man on the telly shouts, "there's more!" "De-duplicate" is easy enough; that's done with the second commit in this PR. But what do we mean by "fix"?
What's in a name?
"It's a naming thing; you wouldn't understand". Which is more important in thinking about a Proposed Edit Contribution: the fact that it's an Edit Contribution or the fact that it's a Proposed Contribution? Whichever way we answer that, it's first and foremost a Contribution, so its naming (and namespacing) should reflect that. Is a Proposed Edit Contribution more like a (future) Proposed Challenge Contribution than an Accepted Edit Contribution? Based on our current understanding, we'd argue "no"; whereas all Proposed Contributions are likely to (at least optionally) be presented together to an Author, the purpose of different types of Contributions differs more than the state of any individual contribution. We'd therefore possibly have separate classes for Contribution::Edit::Proposed than Contribution::Edit::Accepted, but that's a (future) implementation detail that could (arguably) be handed as effectively by adding fields to a single Contribution::Edit class. We don't want to take that decision yet, but we don't want to unnecessarily narrow the options available when that decision is taken. That's a foundational principle of good software architecture. Entities::EditContribution::Proposed smells a bit worse when taking that into consideration, so it's Going Away forthwith.
Repeating ourselves to get DRY later.
As part of the re-evaluation of form objects vs more functional approaches to attribute definition and validation (see Issue #28), we're enthralled by the promise of the dry-rb libraries, particularly Dry::Types and Dry::Validation. It's clearly the follow-on to gems such as Virtus (which we use systematically), led by the original maintainer of Virtus, Piotr Solnica.
Alas, dry-types isn't entirely backward-compatible with Virtus; one can't drop a dry-types custom type into a Virtus value object (such as a form object) and have it work as the Virtus coercion it replaces. We've taken the decision to use dry-types for new code in future (post-0.10.0) releases of the prolog-use_cases Gem, but those use cases would ordinarily expect to reuse some of the code (particularly in the Prolog::Entities namespace) that already exists. To make this happen, we're going to have to develop parallel "ports" of the existing, Virtus-based classes (such as ArticleIdent) with differing names (hypothetically, ArticleIdent2 or ArticleIdentD) which is the Dry::Types-based equivalent. Later, the clients of the Virtus-based classes can be updated.
Is this worth it? We believe it is. It lets us write significantly cleaner, better code going forward, while not forcing a full-stop, rewrite-everything Big Bang that has doomed so many previous efforts. It "keeps the ball moving" without forcing us to bend over backwards writing awkward code simply because "that's the way we've done it up to now".
You say to-may-to; I say to-mah-to…
We've been fairly sloppy up until now, using the word "entity" for any data object that
doesn't necessarily map to a database table as with an ORM model, and
has its identity essentially (but not necessarily formally) tied to the sum of its attribute values.
This is "sloppy" because it conflates two concepts whose differentiation we've been trying to wrap our heads around for years, and only very recently has the Big Bright Light Bulb in the Sky™ flickered on. We would be very amenable to convincing arguments leading to refinement, or even correction, but in general
a value object is an immutable set of data values (when pathologically passed around together-but-separately, often called a "data clump") that has no domain logic, although it may have simple helper methods that simply apply a "literate" gloss to the underlying values. For example, a value object containing an attribute either with the identifier for a user, or with a fixed value when no user is active, might have #guest? and/or #authenticated? Boolean helpers that Do The Obvious Thing based on the attribute value. They do not replace or obscure the attribute value itself.
an entity is a value object with the addition of business logic bound exclusively to the attribute values contained in the entity that do not modify that entity's state. Being a value object, it is immutable; whereas a mutable object has methods (including attribute writers) that modify its state, value objects (and thus entities) have class methods which return new instances of the class. An entity may in fact simply be a wrapper around a value object that delegates to it as appropriate.
This pull request should keep this new understanding in mind as it refines the "edit-contribution entity". It should not take more than a handful of commits to do so.
See Issue #42 for the primary mission of this PR.
"But wait," the man on the telly shouts, "there's more!" "De-duplicate" is easy enough; that's done with the second commit in this PR. But what do we mean by "fix"?
What's in a name?
"It's a naming thing; you wouldn't understand". Which is more important in thinking about a Proposed Edit Contribution: the fact that it's an Edit Contribution or the fact that it's a Proposed Contribution? Whichever way we answer that, it's first and foremost a Contribution, so its naming (and namespacing) should reflect that. Is a Proposed Edit Contribution more like a (future) Proposed Challenge Contribution than an Accepted Edit Contribution? Based on our current understanding, we'd argue "no"; whereas all Proposed Contributions are likely to (at least optionally) be presented together to an Author, the purpose of different types of Contributions differs more than the state of any individual contribution. We'd therefore possibly have separate classes for
Contribution::Edit::ProposedthanContribution::Edit::Accepted, but that's a (future) implementation detail that could (arguably) be handed as effectively by adding fields to a singleContribution::Editclass. We don't want to take that decision yet, but we don't want to unnecessarily narrow the options available when that decision is taken. That's a foundational principle of good software architecture.Entities::EditContribution::Proposedsmells a bit worse when taking that into consideration, so it's Going Away forthwith.Repeating ourselves to get DRY later.
As part of the re-evaluation of form objects vs more functional approaches to attribute definition and validation (see Issue #28), we're enthralled by the promise of the dry-rb libraries, particularly
Dry::TypesandDry::Validation. It's clearly the follow-on to gems such as Virtus (which we use systematically), led by the original maintainer of Virtus, Piotr Solnica.Alas,
dry-typesisn't entirely backward-compatible with Virtus; one can't drop adry-typescustom type into a Virtus value object (such as a form object) and have it work as the Virtus coercion it replaces. We've taken the decision to usedry-typesfor new code in future (post-0.10.0) releases of theprolog-use_casesGem, but those use cases would ordinarily expect to reuse some of the code (particularly in theProlog::Entitiesnamespace) that already exists. To make this happen, we're going to have to develop parallel "ports" of the existing, Virtus-based classes (such asArticleIdent) with differing names (hypothetically,ArticleIdent2orArticleIdentD) which is theDry::Types-based equivalent. Later, the clients of the Virtus-based classes can be updated.Is this worth it? We believe it is. It lets us write significantly cleaner, better code going forward, while not forcing a full-stop, rewrite-everything Big Bang that has doomed so many previous efforts. It "keeps the ball moving" without forcing us to bend over backwards writing awkward code simply because "that's the way we've done it up to now".
You say to-may-to; I say to-mah-to…
We've been fairly sloppy up until now, using the word "entity" for any data object that
This is "sloppy" because it conflates two concepts whose differentiation we've been trying to wrap our heads around for years, and only very recently has the Big Bright Light Bulb in the Sky™ flickered on. We would be very amenable to convincing arguments leading to refinement, or even correction, but in general
#guest?and/or#authenticated?Boolean helpers that Do The Obvious Thing based on the attribute value. They do not replace or obscure the attribute value itself.This pull request should keep this new understanding in mind as it refines the "edit-contribution entity". It should not take more than a handful of commits to do so.