Release 0.3.0: fix CI timezone drift bound, refresh guides, bump version

Author: kipcole9

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 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).
 
-## [Unreleased]
+## [0.3.0] - 2026-07-23
 
 ### Added
 

README.md

@@ -65,7 +65,7 @@ Add `localize_ecto` to your dependencies:
 ```elixir
 def deps do
   [
-    {:localize_ecto, "~> 0.1.0"}
+    {:localize_ecto, "~> 0.3.0"}
   ]
 end
 ```
@@ -115,4 +115,4 @@ If a PostgreSQL upgrade links a newer ICU library whose collation data changed 
 
 Copyright 2026 Kip Cole
 
-Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/elixir-localize/localize_ecto/blob/v0.1.0/LICENSE.md).
+Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/elixir-localize/localize_ecto/blob/v0.3.0/LICENSE.md).

guides/collations_in_postgres.md

@@ -81,24 +81,30 @@ end
 
 This runs `CREATE COLLATION "de-u-co-phonebk-x-icu" (provider = icu, locale = 'de-u-co-phonebk')`. The name matches what `Localize.Ecto.Collation` resolves the locale to, so from then on `collate(p.name, "de-u-co-phonebk")` works with no further configuration. German phonebook order treats `ü` as `ue`: standard German sorts `Mueller, Muller, Müller` while phonebook order sorts `Mueller, Müller, Muller`. Other collation types include `zh-u-co-stroke` and `zh-u-co-zhuyin` for Chinese stroke and Bopomofo orderings, and `es-u-co-trad` for traditional Spanish, where `ch` sorts as a single letter.
 
-Other ICU keywords open up collation behaviors beyond language tailoring:
+Other ICU keywords open up collation behaviors beyond language tailoring. `Localize.Ecto.Migration.create_collation/2` accepts them as tailoring options using the `Localize.Collation.Options` vocabulary, and query-time resolution carries the same keywords, so the locale-with-keywords form works end to end without naming anything:
 
-* Numeric ordering (`-u-kn`) compares digit sequences by numeric value, giving natural sort: `file1, file2, file10` instead of `file1, file10, file2`.
+* Numeric ordering (`-u-kn`, option `numeric: true`) compares digit sequences by numeric value, giving natural sort: `file1, file2, file10` instead of `file1, file10, file2`.
 
   ```elixir
-  create_collation("und-u-kn", name: "natural_sort")
+  # In a migration
+  create_collation("en", numeric: true)
+
+  # In queries — resolves to the collation created above
+  from f in Upload, order_by: collate(f.name, "en-u-kn-true")
   ```
 
-* Strength reduction (`-u-ks-level2`) ignores case differences. Combined with `deterministic: false` this yields a collation under which `'HELLO' = 'hello'` is true — case-insensitive matching without `citext` or `lower()` wrappers, at the cost that `LIKE` and pattern matching cannot use the collation.
+* Strength reduction (`-u-ks-level2`, option `strength: :secondary`) ignores case differences; `strength: :primary` ignores accents too. These strengths default to a nondeterministic collation — the only mode in which `'HELLO' = 'hello'` is actually true — giving case-insensitive matching without `citext` or `lower()` wrappers, at the cost that `LIKE` and pattern matching cannot use the collation (PostgreSQL 18 lifts the `LIKE` restriction). A unique index over such a collation enforces case-insensitive uniqueness:
 
   ```elixir
-  create_collation("und-u-ks-level2", name: "case_insensitive", deterministic: false)
+  create_collation("und", strength: :secondary)
+  create index("users", [collated(:email, "und-u-ks-level2")], unique: true)
   ```
 
-Named collations like these are used in queries with the `:collation` option:
+Custom-named collations are used in queries with the `:collation` option:
 
 ```elixir
-from f in File, order_by: collate(f.name, collation: "natural_sort")
+create_collation("und", numeric: true, name: "natural_sort")
+from f in Upload, order_by: collate(f.name, collation: "natural_sort")
 ```
 
-Two practical notes. PostgreSQL normalizes ICU locale identifiers when it stores them, so `und-u-kn-true` is recorded in standard form as `und-u-kn` — pass the standard form to avoid a notice. And because collations live in the database, remember that a collation created in a migration exists per database: test, dev, and production each get theirs when migrations run.
+Two practical notes. PostgreSQL normalizes ICU locale identifiers when it stores them (`und-u-kn-true` is recorded as `und-u-kn`), which can produce a server notice at creation time — harmless, and the collation's name is unaffected. And because collations live in the database, remember that a collation created in a migration exists per database: test, dev, and production each get theirs when migrations run.

guides/using_localize_ecto.md

@@ -107,15 +107,21 @@ from p in Product, order_by: collate(p.name, "de-u-co-phonebk")
 
 The difference is real: standard German sorts `Mueller, Muller, Müller` while phonebook order treats `ü` as `ue` and sorts `Mueller, Müller, Muller`.
 
-Custom names and other ICU tailorings are supported through options:
+Custom names and other ICU tailorings are supported through options, using the same vocabulary as `Localize.Collation.Options`:
 
 ```elixir
 create_collation("de-u-co-phonebk", name: "german_phonebook")
 
-create_collation("und-u-ks-level2", name: "case_insensitive", deterministic: false)
+# Case-insensitive: secondary strength defaults to a
+# nondeterministic collation, the only mode in which case
+# variants actually compare equal
+create_collation("und", strength: :secondary)
+
+# Natural sort: "file2" before "file10"
+create_collation("en", numeric: true)
 ```
 
-The second example creates a nondeterministic, case-insensitive collation from ICU's `ks-level2` (strength: secondary) tailoring — useful for case-insensitive equality, with the caveats described in the [README](https://hexdocs.pm/localize_ecto/readme.html#deterministic-collations-and-unicode-normalization).
+Query-time resolution carries the same `-u-` keywords, so a tailored collation created under its default name is found automatically — `collate(f.name, "en-u-kn-true")` after `create_collation("en", numeric: true)`. See [Collations in PostgreSQL](https://hexdocs.pm/localize_ecto/collations_in_postgres.html) for the caveats around nondeterministic collations.
 
 ## Matching against a different server
 

mix.exs

@@ -1,7 +1,7 @@
 defmodule LocalizeEcto.MixProject do
   use Mix.Project
 
-  @version "0.2.0"
+  @version "0.3.0"
   @source_url "https://github.com/elixir-localize/localize_ecto"
 
   def project do

test/localize/ecto/audit_test.exs

@@ -67,10 +67,13 @@ defmodule Localize.Ecto.AuditTest do
     test "the application zone inventory is known to the server" do
       audit = Audit.timezone_audit(TestRepo)
 
-      # Both inventories track IANA; a handful of drift entries can
-      # appear when tzdata versions differ, but wholesale divergence
-      # means a broken inventory on one side.
-      assert length(audit.unknown_to_server) < 10
+      # Both inventories track IANA; dozens of drift entries can
+      # appear when the server's tzdata lags CLDR (CI containers
+      # often trail by a release), but wholesale divergence means a
+      # broken inventory on one side. Bound the drift at 10% of the
+      # application inventory.
+      application_zones = length(Localize.DateTime.Timezone.known_timezones())
+      assert length(audit.unknown_to_server) < div(application_zones, 10)
       assert is_list(audit.unknown_to_application)
     end
   end