Correct the Unix lock-file cleanup documentation

[mmashwani]

Severity: Documentation bug (the 3.29.7 concepts guide states the opposite of the implemented lock-path contract)

Summary

I found a direct contradiction in version 3.29.7. The concepts guide says Unix
and macOS delete the native lock file reliably after release. The implementation
and class documentation intentionally leave the file in place because unlinking
can split waiters across different inodes and break mutual exclusion.

This distinction affects cleanup expectations, filesystem provisioning, and
protocol design, so the public concepts guide should describe the implemented
stable-path behavior.

Environment

• documentation/version: filelock 3.29.7
• source: commit 1efb8932c08789deb08ad93a91d8996cc36bb9cc
• affected page: docs/concepts.rst, OS-level locking section
• related change: PR Keep Unix lock files after release #577, "Keep Unix lock files after release"

Reproduction

1. Read the Unix and macOS cleanup paragraph in
   docs/concepts.rst.
2. Compare it with
   UnixFileLock's class contract
   and
   UnixFileLock._release().
3. Observe that _release() unlocks and closes without unlinking.

Observed vs expected

Observed:

Documentation: Unix and macOS delete the lock file reliably after release.
Implementation: The native Unix lock file is intentionally left in place.

Expected:

The concepts guide explains that the stable Unix pathname is intentional and
required to avoid split-inode mutual-exclusion failures.

Root cause (verified in source, 3.29.7)

PR #577 was merged on 2026-07-02 and removed Unix release-time unlinking to fix
the waiter split described in #574. The class docstring and _release() reflect
that change, but the concepts guide retains the earlier cleanup claim introduced
during the previous cleanup behavior.

Suggested fix

Replace the Unix cleanup paragraph with the implemented contract:

• Unix and macOS native lock files remain after release.
• The persistent empty file does not mean the lock is held.
• Preserving the pathname prevents contenders from coordinating through
  different inodes.
• Applications may remove a lock file only when they can prove the complete
  lock protocol is quiescent.

Review generated API text and changelog references for the same stale claim.

Verification

• Documentation matches UnixFileLock._release() and PR Keep Unix lock files after release #577.
• Examples do not use lock-file absence as the native ownership signal.
• Windows best-effort cleanup remains described separately.
• Soft locks remain documented as existence locks that delete their owned file
  on release.

I did not find an existing upstream issue or PR for this exact documentation
contradiction. Targeted searches for Unix cleanup documentation delete lock file and concepts.rst Unix lock file cleanup found no duplicate. Issue #526
appeared in one search, but it asks for read/write lock support on network
filesystems and is not a duplicate.

Current workaround

Treat the implementation and UnixFileLock class docstring as authoritative.
Do not infer that a persistent Unix native lock file is orphaned or held.