make_taggable 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be8e033e4d750a0bc75a77f652351843c096f38d8f8332f56e9d642e2085f12b
-  data.tar.gz: 698531499c7e7636b241b854cf60e2e2aee3799af3dba3d2d8a5f1ae2ff954f1
+  metadata.gz: 7d3a7c89a48d79f6d985b8290d88007368ecdf983789a7e4881662724a1060a9
+  data.tar.gz: dda60e219b50e10b8948b6b9b260e703d8815f43bd200b1c434875144ae68071
 SHA512:
-  metadata.gz: c2f772cac980b2bab6c101c087916f3083f519aaec61c8c45ad4cd8750ab95dc6f9534d4ac2a511a6411872590dcfb4a58c3af7f68611458365ff8e5ce024866
-  data.tar.gz: 50aae450f2dfd5923ecf8c18a348b6e7e27b761d71d7fd59b61498c338341f607b735194b2a56da154624ad71e84a748f3a3aebec84beb0a6a21b3a7d0f244b0
+  metadata.gz: 7aa7e8b6c7190cbc8fbdcaf54fd5f49bf8f877c3161c7466e7df98eefd8f14eaa208391b47fa5a328db563d489d5e9a6f82b3bfd4b0ce770cdedbf3423f958bc
+  data.tar.gz: 0e868727368e57e72fe627cbbc4b7a4dc2077e459d6ac9131732788fec26a88037bd7ed12cb86a35f3b8308b3df7fa238319c24628f39e698c073e7d0dd8fa68

data/CHANGELOG.md

@@ -5,7 +5,41 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - unreleased
+## [1.1.1] - 2026-08-22
+
+### Fixed
+
+- Documentation examples used `params.expect` and `ActiveRecord::Migration[8.0]`, neither of which
+  exists on Active Record 7.2 -- the version the gem promises to support. Both are corrected, and
+  `spec/docs_spec.rb` now fails the build if either creeps back.
+
+### Internal
+
+- Added documentation checks to the suite: every Ruby block in the README and `docs/` must parse,
+  example migrations must declare a version the floor accepts, version-sensitive calls must be
+  shown alongside an alternative, and relative links must resolve. They run on every Rails version
+  in the matrix.
+
+## [1.1.0] - 2026-08-22
+
+### Added
+
+- A migration adding `taggings_unowned_idx`, a partial unique index that stops duplicate unowned
+  taggings at the database level. `taggings_idx` never could: it spans the nullable tagger columns,
+  and SQL compares nulls as distinct, so only the model validation stood in the way and a validation
+  cannot win a race. MySQL has no partial indexes, so the migration is a no-op there.
+
+  Install it with `rails make_taggable_engine:install:migrations`. If it fails, the table already
+  holds duplicates -- see [docs/database.md](docs/database.md).
+
+### Internal
+
+- The suite runs in random order. Examples were leaking state into each other: tagging declarations
+  on the shared models, and the library configuration -- one example leaving `remove_unused_tags`
+  on could make an unrelated example fail a foreign key check. Both are now snapshotted and restored
+  around every example.
+
+## [1.0.0] - 2026-08-22
 
 ### Breaking
 

data/CONTRIBUTING.md

@@ -47,10 +47,16 @@ bundle exec appraisal rake
 
 ### A note on test ordering
 
-The suite runs in defined order. Several examples mutate shared model classes — adding a context to
-`TaggableModel`, flipping `preserve_tag_order` — and rely on siblings having run first. Randomising
-the order exposes this. Making those examples self-contained is welcome work; until then, please
-don't add new examples that depend on a sibling's side effects.
+The suite runs in random order, so an example that depends on a sibling having run first will fail
+sooner or later. Reproduce a failure with the seed it reports:
+
+```shell
+bundle exec rspec --order random:12345
+```
+
+Examples are free to change global state — the tagging declarations on the shared models, and the
+`MakeTaggable` configuration — because `spec_helper.rb` snapshots both and restores them after every
+example. Anything else you make global is yours to clean up.
 
 ## Documentation
 
@@ -58,6 +64,12 @@ Prose documentation lives in [docs/](docs). API documentation is YARD comments i
 the style already there: a `##` opening line, a description, a blank line, then tags with real Ruby
 types.
 
+`spec/docs_spec.rb` holds the prose to the versions the gemspec promises. It checks that every Ruby
+block parses, that no example declares a migration version newer than the supported floor, that
+calls the floor does not have are shown alongside an alternative, and that every relative link
+resolves. It runs with the rest of the suite, so it runs on every Rails version in the matrix --
+including the oldest, which is where documentation written on the newest tends to break.
+
 Build it locally with `bundle exec yard doc`.
 
 ## Releasing

data/README.md

@@ -1,7 +1,8 @@
 # MakeTaggable
 
-[![Gem Version](https://badge.fury.io/rb/make_taggable.svg)](https://badge.fury.io/rb/make_taggable)
-![CI](https://github.com/MatthewKennedy/make_taggable/workflows/CI/badge.svg)
+[![Gem Version](https://img.shields.io/gem/v/make_taggable)](https://rubygems.org/gems/make_taggable)
+[![Downloads](https://img.shields.io/gem/dt/make_taggable)](https://rubygems.org/gems/make_taggable)
+[![CI](https://github.com/MatthewKennedy/make_taggable/actions/workflows/ci.yml/badge.svg)](https://github.com/MatthewKennedy/make_taggable/actions/workflows/ci.yml)
 [![Standard Rb](https://github.com/MatthewKennedy/make_taggable/actions/workflows/standard-ci.yml/badge.svg)](https://github.com/MatthewKennedy/make_taggable/actions/workflows/standard-ci.yml)
 
 Tagging for Active Record models, across any number of named contexts.
@@ -12,7 +13,7 @@ order they were added in, and be cached on the record for display.
 
 ## Requirements
 
-| | |
+| Component | Supported |
 |---|---|
 | Ruby | 3.2 or newer |
 | Active Record | 7.2 or newer |
@@ -35,44 +36,73 @@ rails db:migrate
 
 ```ruby
 class Book < ApplicationRecord
-  make_taggable            # the :tags context
-  make_taggable :genres    # and one of your own
+  make_taggable            # the :tags context, for free-form tags
+  make_taggable :genres    # a context of your own, for a curated set
 end
 ```
 
+Each context is a separate set of tags, with its own list:
+
 ```ruby
-book = Book.create!(title: "Dune", tag_list: "sci-fi, classic")
+book = Book.create!(title: "Dune", genre_list: "sci-fi, classic")
+
+book.genre_list                  # => ["sci-fi", "classic"]
+```
 
-book.tag_list                    # => ["sci-fi", "classic"]
-book.tag_list.add("desert")
-book.tag_list.remove("classic")
+Add and remove individual tags. Nothing is written until you save:
+
+```ruby
+book.genre_list.add("space opera")
+book.genre_list.remove("classic")
 book.save
 
-book.genre_list = "science fiction"
+book.genre_list                  # => ["sci-fi", "space opera"]
+book.genres                      # => [#<MakeTaggable::Tag name: "sci-fi">, #<MakeTaggable::Tag name: "space opera">]
+```
+
+Assigning replaces the whole list, and the two contexts never touch each other:
+
+```ruby
+book.tag_list = "desert, chosen-one, re-read"
 book.save
+
+book.tag_list                    # => ["desert", "chosen-one", "re-read"]
+book.genre_list                  # => ["sci-fi", "space opera"]
 ```
 
 Find them again:
 
 ```ruby
 Book.tagged_with("sci-fi")                             # carries this tag
-Book.tagged_with(["sci-fi", "desert"])                 # carries both
+Book.tagged_with(["sci-fi", "space opera"])            # carries both
 Book.tagged_with(["sci-fi", "fantasy"], any: true)     # carries either
-Book.tagged_with(["sci-fi"], exclude: true)            # carries neither
+Book.tagged_with(["fantasy"], exclude: true)           # carries neither
+```
+
+Scope a query to one context, and tags in the others stop counting:
+
+```ruby
+Book.tagged_with("sci-fi", on: :genres)                # => [#<Book title: "Dune">]
+Book.tagged_with("sci-fi", on: :tags)                  # => []
+```
 
-Book.tag_counts_on(:genres)                            # tags with usage counts
+Counts, for tag clouds and "most used" lists:
+
+```ruby
+Book.tag_counts_on(:genres)                            # tags carrying a `count`
 Book.top_genres(10)
 ```
 
 Tags are ordinary attributes as far as your controller is concerned:
 
 ```ruby
-params.expect(book: [:title, :tag_list])
+params.expect(book: [:title, :tag_list])            # Rails 8
+params.require(:book).permit(:title, :tag_list)     # Rails 7.2
 ```
 
 ## Documentation
 
-| | |
+| Guide | Covers |
 |---|---|
 | [Getting started](docs/getting-started.md) | Install, first tagged model, reading and writing |
 | [Tag contexts](docs/contexts.md) | Multiple contexts, ordered tags, contexts created at runtime |

data/UPGRADING.md

@@ -23,6 +23,10 @@ This release renames the declaration methods and changes how delimiters are esca
 
 4. Requirements are now Ruby 3.2 and Active Record 7.2 or newer.
 
+Note for anyone upgrading past 1.0: a later migration adds a unique index
+preventing duplicate unowned taggings. If it fails, your taggings table
+already holds duplicates -- docs/database.md has a snippet to clear them.
+
 Install any new migrations:
 
     rails make_taggable_engine:install:migrations

data/db/migrate/6_add_unowned_taggings_unique_index.rb

@@ -0,0 +1,18 @@
+class AddUnownedTaggingsUniqueIndex < ActiveRecord::Migration[7.2]
+  # taggings_idx spans tagger_id and tagger_type, which are NULL on every
+  # tagging nobody owns. SQL compares NULLs as distinct, so that index does not
+  # stop two identical unowned taggings -- only the model validation does, and a
+  # validation cannot win a race between two concurrent writes.
+  #
+  # A partial index closes it. MySQL has no partial indexes, so it keeps the
+  # validation on its own.
+  def change
+    return if MakeTaggable::Utils.using_mysql?
+
+    add_index MakeTaggable.taggings_table,
+      [:tag_id, :taggable_id, :taggable_type, :context],
+      unique: true,
+      where: "tagger_id IS NULL",
+      name: "taggings_unowned_idx"
+  end
+end

data/docs/caching.md

@@ -10,7 +10,7 @@ There is no setting. Add a column named `cached_<singular context>_list` and cac
 itself on for that context:
 
 ```ruby
-class AddCachedTagListToBooks < ActiveRecord::Migration[8.0]
+class AddCachedTagListToBooks < ActiveRecord::Migration[7.2]
   def change
     add_column :books, :cached_tag_list, :string
     add_column :books, :cached_genre_list, :string

data/docs/contexts.md

@@ -46,10 +46,15 @@ Calling `make_taggable` again adds contexts rather than replacing them, which is
 subclass extend its parent:
 
 ```ruby
+class Book < ApplicationRecord
+  make_taggable
+end
+
 class Manual < Book
   make_taggable :audiences
 end
 
+Book.tag_types   # => [:tags]
 Manual.tag_types # => [:tags, :audiences]
 ```
 
@@ -134,7 +139,7 @@ tags, `Market.count` returns every tag in the table, and reloading a record give
 `MakeTaggable::Tag` back. Add the column to get real separation:
 
 ```ruby
-class AddTypeToTags < ActiveRecord::Migration[8.0]
+class AddTypeToTags < ActiveRecord::Migration[7.2]
   def change
     add_column MakeTaggable.tags_table, :type, :string
     add_index MakeTaggable.tags_table, :type

data/docs/database.md

@@ -34,22 +34,39 @@ That suits read-heavy tagging. If your application writes taggings in bulk, the
 looking at — every index is maintained on insert, and several of the standalone ones are prefixes of
 composites that already exist. Drop what your queries do not use.
 
-### The unique index does not stop duplicate unowned taggings
+### Duplicate unowned taggings
 
 `taggings_idx` is unique across
 `[tag_id, taggable_id, taggable_type, context, tagger_id, tagger_type]`. Because `tagger_id` and
-`tagger_type` are null for unowned taggings, and SQL treats nulls as distinct, **the database will
-accept two identical unowned taggings**. Only the Active Record uniqueness validation prevents them,
-and a validation cannot prevent a race between two concurrent writes.
+`tagger_type` are null on every tagging nobody owns, and SQL compares nulls as distinct, that index
+does not stop two identical unowned taggings. Only the model validation does, and a validation
+cannot win a race between two concurrent writes.
 
-If duplicate taggings would be a problem for you, add a partial unique index. On PostgreSQL:
+Migration 6 closes it with a partial unique index, `taggings_unowned_idx`, covering
+`[tag_id, taggable_id, taggable_type, context]` where `tagger_id IS NULL`.
+
+**MySQL has no partial indexes**, so it keeps the validation on its own and the migration is a no-op
+there. If duplicate taggings would be a serious problem on MySQL, the usual workaround is a
+generated column holding a sentinel for the null tagger, indexed uniquely alongside the rest.
+
+If the migration fails with a uniqueness error, the table already contains duplicates. Remove them
+first:
 
 ```ruby
-add_index :taggings,
-  [:tag_id, :taggable_id, :taggable_type, :context],
-  unique: true,
-  where: "tagger_id IS NULL",
-  name: "taggings_unowned_idx"
+duplicates = MakeTaggable::Tagging
+  .where(tagger_id: nil)
+  .group(:tag_id, :taggable_id, :taggable_type, :context)
+  .having("COUNT(*) > 1")
+  .pluck(Arel.sql("MIN(id), COUNT(*)"))
+
+duplicates.each do |keep_id, _count|
+  tagging = MakeTaggable::Tagging.find(keep_id)
+  MakeTaggable::Tagging
+    .where(tagger_id: nil, tag_id: tagging.tag_id, taggable_id: tagging.taggable_id,
+      taggable_type: tagging.taggable_type, context: tagging.context)
+    .where.not(id: keep_id)
+    .delete_all
+end
 ```
 
 ## PostgreSQL

data/docs/getting-started.md

@@ -83,15 +83,19 @@ class BooksController < ApplicationController
   private
 
   def book_params
-    params.expect(book: [:title, :tag_list])
+    params.expect(book: [:title, :tag_list])       # Rails 8
+    # params.require(:book).permit(:title, :tag_list)   # Rails 7.2
   end
 end
 ```
 
+`params.expect` arrived in Rails 8. On Rails 7.2 use `require` and `permit`, as commented above.
+
 To accept an array of tags from a multi-select, permit it as one:
 
 ```ruby
-params.expect(book: [:title, {tag_list: []}])
+params.expect(book: [:title, {tag_list: []}])      # Rails 8
+params.require(:book).permit(:title, tag_list: []) # Rails 7.2
 ```
 
 ## Find tagged records

data/docs/querying.md

@@ -6,18 +6,18 @@
 pagination.
 
 ```ruby
-User.tagged_with("awesome").by_join_date.limit(20)
+Book.tagged_with("sci-fi").order(published_at: :desc).limit(20)
 ```
 
 By default every tag given must be present:
 
 ```ruby
-User.tagged_with(["awesome", "cool"])              # carries awesome AND cool
-User.tagged_with(["awesome", "cool"], any: true)   # carries awesome OR cool
-User.tagged_with(["awesome", "cool"], exclude: true) # carries NEITHER
+Book.tagged_with(["sci-fi", "classic"])                # carries sci-fi AND classic
+Book.tagged_with(["sci-fi", "classic"], any: true)     # carries sci-fi OR classic
+Book.tagged_with(["sci-fi", "classic"], exclude: true) # carries NEITHER
 ```
 
-Passing nothing matches nothing. `User.tagged_with([])` and `User.tagged_with("")` both return an
+Passing nothing matches nothing. `Book.tagged_with([])` and `Book.tagged_with("")` both return an
 empty relation rather than every record — worth knowing when the tags come from user input.
 
 ### Options
@@ -27,7 +27,7 @@ empty relation rather than every record — worth knowing when the tags come fro
 | `:any` | Match records carrying at least one of the tags |
 | `:exclude` | Match records carrying none of the tags |
 | `:match_all` | Match records carrying only these tags and no others |
-| `:wild` | Match tags *containing* the given text, i.e. `%awesome%` |
+| `:wild` | Match tags *containing* the given text, i.e. `%sci%` |
 | `:on` | Restrict to one context |
 | `:owned_by` | Restrict to tags applied by one tagger |
 | `:order_by_matching_tag_count` | With `:any`, order by how many tags matched, most first |
@@ -37,15 +37,15 @@ empty relation rather than every record — worth knowing when the tags come fro
 `:wild` combines with `:any` or `:exclude`:
 
 ```ruby
-User.tagged_with(["awe", "co"], any: true, wild: true)
+Book.tagged_with(["sci", "clas"], any: true, wild: true)
 ```
 
 Contexts are matched one call at a time, so chain to combine them:
 
 ```ruby
-User
-  .tagged_with(["awesome", "cool"], on: :tags, any: true)
-  .tagged_with(["smart", "shy"], on: :skills, any: true)
+Book
+  .tagged_with(["sci-fi", "fantasy"], on: :genres, any: true)
+  .tagged_with(["desert", "space"], on: :tags, any: true)
 ```
 
 ### Case sensitivity
@@ -105,6 +105,9 @@ noticeably cheaper on a large table.
 
 ## Related records
 
+These examples switch to a `User` model tagged on `:skills` — sharing tags is easiest to picture
+with people.
+
 Records sharing tags with this one, ordered by how many tags matched:
 
 ```ruby

data/lib/make_taggable/version.rb

@@ -6,5 +6,5 @@ module MakeTaggable
   #
   # @return [String]
   #
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: make_taggable
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Matthew Kennedy
@@ -46,6 +46,7 @@ files:
 - db/migrate/3_change_tag_name_collation_mysql.rb
 - db/migrate/4_add_index_to_tags.rb
 - db/migrate/5_add_index_to_taggings.rb
+- db/migrate/6_add_unowned_taggings_unique_index.rb
 - docs/caching.md
 - docs/configuration.md
 - docs/contexts.md
@@ -116,6 +117,10 @@ post_install_message: |
 
   4. Requirements are now Ruby 3.2 and Active Record 7.2 or newer.
 
+  Note for anyone upgrading past 1.0: a later migration adds a unique index
+  preventing duplicate unowned taggings. If it fails, your taggings table
+  already holds duplicates -- docs/database.md has a snippet to clear them.
+
   Install any new migrations:
 
       rails make_taggable_engine:install:migrations