add gotchas, release logs and process

use uv consistently

Author: derek73

AGENTS.md

@@ -15,7 +15,7 @@ Branch naming: `fix/issue-NNN-short-description` or `feat/short-description`.
 
 # Run all tests (includes --doctest-modules, so doctests in nameparser/ are also run;
 # the dual-parametrize fixture doubles the count, so ~370 methods → ~740 results)
-uv run pytest
+uv run pytest  # --doctest-modules is set in pyproject.toml, so doctests run automatically
 
 # Run a single test file / class / method
 uv run pytest tests/test_python_api.py
@@ -28,14 +28,32 @@ uv run mypy nameparser/
 uv run ruff check nameparser/
 
 # Debug how a specific name string is parsed (prints HumanName repr)
-python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
+uv run python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
 
 # Build docs
-sphinx-build -b html docs dist/docs
-
-# Build package for release
-python setup.py sdist bdist_wheel
-twine upload dist/*
+uv run sphinx-build -b html docs dist/docs
+
+# Maintain docs/release_log.rst as changes land:
+# - Keep an "Unreleased" entry at the top: `* X.Y.Z - Unreleased`
+# - Add one bullet per notable change; prefix with Add/Fix/Remove/Change
+# - Reference the issue or PR in parentheses: (#123) or (#123, #124)
+#   Use "closes #N" when the change directly resolves the issue
+# - Version is decided at release time (patch/minor/major per semver)
+# - Format matches existing entries — see 1.3.0 block for a current example
+
+# Release checklist (PyPI publish is triggered automatically by GitHub Actions on release creation)
+# 0. Review docs/ for anything stale — especially usage.rst (examples, API surface)
+#    and any .rst files that reference config constants or HumanName kwargs
+#    Also review AGENTS.md for stale commands, architecture notes, or gotchas
+# 1. Bump VERSION in nameparser/_version.py
+# 2. Stamp "Unreleased" → "X.Y.Z - Month DD, YYYY" in docs/release_log.rst
+# 3. git commit + git tag -a vX.Y.Z -m "Release X.Y.Z"
+# 4. git push origin master && git push origin vX.Y.Z  ← tag must be pushed separately before gh release create
+# 5. gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
+# 6. Close the vX.Y.Z milestone and create a new "Next Release" one:
+#    MILESTONE=$(gh api repos/derek73/python-nameparser/milestones --jq '.[] | select(.title=="vX.Y.Z") | .number')
+#    gh api -X PATCH repos/derek73/python-nameparser/milestones/$MILESTONE -f state=closed
+#    gh api -X POST repos/derek73/python-nameparser/milestones -f title="Next Release"
 ```
 
 Enable debug logging to see the parser's internal decisions:
@@ -88,6 +106,20 @@ Each named attribute (`title`, `first`, etc.) is a `@property` that joins its co
 3. Add `self.x = x if x is not None else self.C.x` in body — use `is not None`, not `or`, to allow falsy values like `""`
 4. conftest auto-restores scalar CONSTANTS between tests, but tests that *set* CONSTANTS mid-run still need their own try/finally
 
+## Gotchas
+
+**`suffix_not_acronyms` vs `is_an_initial` tension** — single-letter roman numeral suffixes (`i`, `v`) are in `suffix_not_acronyms` but also match the `is_an_initial` regex (single uppercase letter), so `is_suffix()` rejects them. Two separate code paths need context-aware workarounds: (1) suffix-comma detection uses `are_suffixes_after_comma()` which bypasses `is_suffix()` for `suffix_not_acronyms` members; (2) lastname-comma post-comma parsing uses `is_suffix_at_lastname_comma_end()` which only fires when `nxt is None` and `len(parts)==2` (no `parts[2]` suffix segment). See issues #136, #144.
+
+**Expected-failure tests use `@pytest.mark.xfail`** — the conftest parametrized fixture breaks `@unittest.expectedFailure`; always use `@pytest.mark.xfail` instead.
+
+**`lc()` strips only trailing periods** — `'M.D.'` → `'m.d'`, not `'md'`. Exception keys in `capitalization_exceptions` are dot-free, so lookups must also try `.replace('.', '')`.
+
+**`docs/usage.rst` contains live doctests** — edits can break `uv run pytest` (run via `--doctest-modules`). Verify new examples with `python3 -c "..."` before committing.
+
+**`initials_separator` is intra-group only** — it controls the joiner between consecutive initials *within* a name group (e.g. two middle names in `middle_list`). Spaces *between* groups come from `initials_format`. To fully concatenate initials you need both `initials_separator=""` and `initials_format="{first}{middle}{last}"`.
+
+**`pr/NNN` local branches** track upstream PRs — don't commit to them by accident. Check `git branch --show-current` before starting work.
+
 ### Tests (`tests/`)
 
-Tests run under **pytest** (via `.venv/bin/pytest`) and are split one file per concern (`tests/test_titles.py`, `tests/test_suffixes.py`, etc.). `tests/base.py` holds `HumanNameTestBase` — a plain (non-`unittest`) base whose `m()` helper is a custom assert that prints the original name string on failure (plus thin `assert*` shims so the moved test bodies are unchanged). `tests/conftest.py` defines an autouse fixture that runs **every test twice** — once with `empty_attribute_default = ''` and once with `None` — so reported counts are doubled (e.g. 11 methods → 22 results); it also snapshots/restores the scalar `CONSTANTS` config around each test to keep tests order-independent. `TEST_NAMES` (in `tests/test_variations.py`) is a list of name strings permuted into comma-separated variants as a regression check. Tests that should fail use `@pytest.mark.xfail`. When adding a parsing case, add it to the relevant `tests/test_*.py` file and consider adding the base form to `TEST_NAMES`.
+Tests run under **pytest** (via `uv run pytest`) and are split one file per concern (`tests/test_titles.py`, `tests/test_suffixes.py`, etc.). `tests/base.py` holds `HumanNameTestBase` — a plain (non-`unittest`) base whose `m()` helper is a custom assert that prints the original name string on failure (plus thin `assert*` shims so the moved test bodies are unchanged). `tests/conftest.py` defines an autouse fixture that runs **every test twice** — once with `empty_attribute_default = ''` and once with `None` — so reported counts are doubled (e.g. 11 methods → 22 results); it also snapshots/restores the scalar `CONSTANTS` config around each test to keep tests order-independent. `TEST_NAMES` (in `tests/test_variations.py`) is a list of name strings permuted into comma-separated variants as a regression check. Tests that should fail use `@pytest.mark.xfail`. When adding a parsing case, add it to the relevant `tests/test_*.py` file and consider adding the base form to `TEST_NAMES`.