Document raw column writes as the user's responsibility - #82
Merged
Conversation
igor-alexandrov
force-pushed
the
document-raw-writes
branch
from
August 18, 2026 13:54
a11a9aa to
c4113f5
Compare
Issue #36 asked whether Metka should de-duplicate tags. The answer split along the write path years ago without anyone recording it: tag_list= goes through the parser, whose TagList is a Set, so it de-duplicates; assigning the array column directly is a plain ActiveRecord attribute write that Metka never sees, so it stores exactly what it is given. This makes the split the documented contract rather than an accident. Metka owns the *_list API; the column belongs to the schema, and normalizing direct writes is the caller's job. The README section also warns about the observable consequence of ignoring that: duplicates stored raw are counted twice by tag clouds, which aggregate the raw array elements. Two tests pin the contract from both sides so a future change to either half shows up as a deliberate decision, not drift. Closes #36 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
igor-alexandrov
force-pushed
the
document-raw-writes
branch
from
August 18, 2026 13:56
c4113f5 to
b045b73
Compare
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.
Settles #36 — "Should tags be de-duplicated?" — by declaring the existing split the contract. Closes #36.
The decision
The question answered itself along the write path years ago; nobody recorded it:
song.tag_list = ["github", "github"]TagListis aSet→ stores["github"]song.tags = ["github", "github"]["github", "github"]This PR makes that the documented contract: Metka owns the
*_listAPI; the column belongs to your schema, and normalizing direct writes is your responsibility.What's in it
tag_list=vs the raw column" section under Tag objects, including the non-obvious consequence found while verifying the issue: duplicates stored raw are counted twice by tag clouds (UNNESTaggregates raw array elements — verified live, three posts tagged onlygithubproduced[["github", 4]]).No behaviour changes — this is documentation plus pins.
Verification
RuboCop: 57 files inspected, no offenses.
mdl README.md: clean (CI lints doc changes).Independent PR off
master, no relation to #79–#81.🤖 Generated with Claude Code