[manav4u]

Addresses #3116.

Add a contributor-guide section covering the attrs choices already used in Trio:

• Explicit aliases for private fields in public constructors, including the Pyright limitation and existing CI check.
• Identity equality for objects such as CancelScope and Task.
• The slots default and a concrete slots=False example from NurseryManager.
• Frozen records versus mutable state, including shallow immutability.

The section links to the relevant attrs documentation and includes a small runnable example. No runtime code or dependency changes.

Validation on current main 7e0dc2d, CPython 3.11.17/Linux:

• Installed the unchanged pinned docs-requirements.txt, including pycparser 3.12 and Sphinx 9.0.4.
• Fresh strict HTML builds (sphinx-build -E -b html -W --keep-going) pass with zero warnings both before and after this patch.
• The example runs; its constructor signature, identity equality and per-instance list defaults were checked. Existing NurseryManager slots and frozen statistics examples were rechecked against current source.
• test_pyright_recognizes_init_attributes passes with the alias plugin loaded before Trio's pytest plugin, as in CI. Unrelated auto-loaded plugins were disabled for this focused check.
• The complete rendered section was visually checked for readable text, code, bullets and layout.

The earlier November 8 build used unpinned documentation dependencies and had 17 baseline warnings. The validation above is a fresh run with the current pinned environment, not a reinterpretation of that earlier result. No full runtime suite, type-checker or CI result is claimed for this documentation-only change.

Prepared with AI assistance.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00000%. Comparing base (7e0dc2d) to head (bf4a6b8).

Additional details and impacted files

@@                 Coverage Diff                  @@
##                main        #3592         +/-   ##
====================================================
+ Coverage   98.16743%   100.00000%   +1.83257%     
====================================================
  Files            128          128                 
  Lines          19972        19588        -384     
  Branches        1399         1335         -64     
====================================================
- Hits           19606        19588         -18     
+ Misses           359            0        -359     
+ Partials           7            0          -7     

see 56 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[A5rocks]

LLM generated docs have always seemed kind of pointless. I guess I can see cases where it helps (non-contributor docs, a really good model, well written and concise prose) but that's not this.