docs: move stranded recipes out of the release log

Actionable knowledge had accumulated in release_log.rst, which readers
consult once at upgrade time and never search for how-to. Relocate it
to the task-oriented pages.

migrate.rst "Before you upgrade" gains:

- The pre-1.3.0 pickle constraint, called out as an ordering hazard.
  A Constants blob written by 1.2.x must be re-pickled ON 1.3/1.4;
  after upgrading, the code that could rewrite it is gone. Every other
  migration step is fixable afterwards, which is why this one cannot
  live in a changelog.
- A replacement table for the warned removals (decode() for bytes,
  set(manager), discard(), Constants()/CONSTANTS.copy(), plain
  attribute assignment, .get()). The section previously assumed a
  clean -W error::DeprecationWarning run and offered nothing to the
  readers who most need it -- those who didn't get one.
- A pointer to tools/differential/ for diffing 1.4 vs 2.0 over the
  reader's own corpus, noting it is source-repo tooling, not installed.

migrate.rst also inlines the casefold example (STRASSE/Straße) and the
two behavior-diff shapes worth grepping fixtures for, both of which
previously redirected to the release log.

locales.rst gains "What works without a pack". The page listed two
packs, so a reader with Arabic or Hebrew data concluded there was no
support -- while the five-script default vocabulary from #269 handles
it out of the box and was documented nowhere but the changelog. Also
records which entries are deliberately held back and how to add them.

Writing that last example surfaced the reason to document it: adding an
honorific to given_name_titles ALONE silently does nothing, because the
field is a marker over titles rather than its own vocabulary. The
doctest caught it; the text now says so.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: derek73

docs/locales.rst

@@ -7,6 +7,54 @@ patronymics, Turkic patronymic markers, and so on. Packs apply only
 when you ask for one by name, and every pack makes the same promise:
 a pack never changes a name it doesn't declare.
 
+What works without a pack
+--------------------------
+
+Most international names need no pack at all. The default vocabulary
+covers five scripts — Latin, Cyrillic, Greek, Arabic and Hebrew, plus
+Devanagari titles — so honorifics, conjunctions and name particles in
+those scripts are recognized out of the box:
+
+.. doctest::
+
+    >>> from nameparser import parse
+    >>> name = parse("الشيخ محمد بن سلمان")
+    >>> name.title, name.given, name.family
+    ('الشيخ', 'محمد', 'بن سلمان')
+    >>> parse("عبد الرحمن محمد").given
+    'عبد الرحمن'
+
+Native-script entries are safe to enable by default precisely because
+they cannot collide with Latin-script names. That rules out the
+reverse: transliterations like ``sri``/``shri`` are *not* in the
+default vocabulary, because they are also ordinary given names in
+Latin script. The same conservatism holds back a handful of native
+entries that collide within their own script — bare ``سيد`` and
+``شيخ`` (common given names), Hebrew ``רב`` (an ordinary word), the
+Arabic ``د.`` abbreviation (it would swallow initials).
+
+If your data is homogeneous enough that a collision can't occur, the
+reasoning behind the default doesn't apply to you — add the entry:
+
+.. doctest::
+
+    >>> from nameparser import Lexicon, Parser
+    >>> lex = Lexicon.default().add(
+    ...     titles={"سيد"}, given_name_titles={"سيد"})
+    >>> name = Parser(lexicon=lex).parse("سيد محمد")
+    >>> name.title, name.given
+    ('سيد', 'محمد')
+
+Both fields, because ``given_name_titles`` is a marker over ``titles``
+rather than a separate vocabulary: ``titles`` makes the word a title at
+all, and listing it in ``given_name_titles`` says the honorific
+precedes the *given* name — as Arabic ones do — so the word after it
+isn't read as a family name. Adding it to ``given_name_titles`` alone
+has no effect.
+
+A pack is for something different: a *structural* rule, like reordering
+a patronymic, that vocabulary alone can't express.
+
 Using a pack
 ------------
 

docs/migrate.rst

@@ -46,6 +46,46 @@ where 1.x returned ``True``. That one *did* warn on 1.4, but nothing
 will tell you on 2.0. If you compare names anywhere, grep for ``==``
 before upgrading and move to ``matches()`` — see `Comparison`_.
 
+One step has to happen *before* you upgrade, because the fix is only
+available on the version you're leaving: a ``Constants`` pickle written
+by nameparser 1.2.x or earlier must be re-pickled under 1.3 or 1.4.
+2.0 refuses to load one, and by then the code that could rewrite it is
+gone.
+
+If your suite did *not* run clean, these are the replacements for the
+warned removals:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 45 55
+
+   * - 1.4 spelling
+     - 2.0 replacement
+   * - ``HumanName(b"...")``, ``manager.add(b"...")``
+     - Decode first: ``HumanName(raw.decode("utf-8"))``
+   * - ``SetManager.add_with_encoding(b"...")``
+     - ``add()``, on already-decoded ``str``
+   * - ``manager()`` (calling a set manager)
+     - ``set(manager)``, or iterate it directly
+   * - ``manager.remove(missing)`` (was tolerant)
+     - ``discard()`` to ignore missing; ``remove()`` now raises
+       ``KeyError`` like ``set.remove``
+   * - ``HumanName(..., constants=None)``
+     - ``Constants()`` for library defaults, or ``CONSTANTS.copy()``
+       for a private snapshot of the current shared config
+   * - ``name['first'] = value``
+     - ``name.first = value``
+   * - ``CONSTANTS.regexes.typo`` (returned ``None``)
+     - ``.get("typo")`` for intentional soft access; attribute access
+       now raises ``AttributeError`` naming the known keys
+   * - ``CONSTANTS.empty_attribute_default``
+     - Gone; empty fields are always ``''``
+
+Finally, if you want to see the difference on your own data rather than
+ours, ``tools/differential/`` in the source repository diffs 1.4 and
+2.0 parses over a corpus of names you supply. It is development
+tooling, not part of the installed package — see its README.
+
 Attribute map
 -------------
 
@@ -263,15 +303,35 @@ behavior:
 
 One behavior changed underneath both methods: components now fold with
 ``str.casefold()`` instead of ``str.lower()``, so more Unicode
-case-pairs compare equal than did under 1.4 (see the 2.0.0 section of
-:doc:`release_log` for the exact rule and examples).
+case-pairs compare equal than did under 1.4. The change is strictly
+more permissive — anything 1.4 matched still matches:
+
+.. doctest::
+
+    >>> parse("Anna STRASSE").matches("Anna Straße")
+    True
 
 Behavior changes
 -----------------
 
 Beyond the API surface mapped above, a handful of parse *outputs*
-differ between 1.4 and 2.0 for specific input shapes — comma-suffix
-routing, maiden-marker detection, an ambiguous-acronym data change, and
-one rendering difference under a custom suffix delimiter. These are
-listed with their reasoning and test coverage in the 2.0.0 section of
-:doc:`release_log`; they aren't repeated here.
+differ between 1.4 and 2.0 for specific input shapes. The full list,
+with reasoning, is in the 2.0.0 section of :doc:`release_log`. These
+are the shapes worth grepping your own fixtures for, because a
+recognized suffix or title now stays in its own field instead of
+landing in ``first``/``last``:
+
+.. doctest::
+
+    >>> HumanName("Andrews, M.D.").last, HumanName("Andrews, M.D.").suffix
+    ('Andrews', 'M.D.')
+    >>> HumanName("Johnson PhD").first, HumanName("Johnson PhD").suffix
+    ('Johnson', 'PhD')
+
+Under 1.4 those read ``first="M.D."``/``last="Andrews"`` and
+``first="Johnson"``/``last="PhD"`` respectively. Two more to check for:
+a maiden marker now fills the ``maiden`` field rather than being folded
+into ``middle``/``last`` (``"Jane Smith née Jones"``), and with a
+custom suffix delimiter configured, a no-space delimiter group renders
+whole (``"RN/CRNA"``) where 1.x split it (``"RN, CRNA"``) — the role
+assignment is identical, only the rendered string differs.