Document the Debian/Ubuntu opentracing build failure

[wbarnha]

Note: Before submitting this pull request, please review our contributing
guidelines.

Description

Docs only. Following the setup steps in the contributing guide on Debian or Ubuntu fails, and the error names nothing you'd connect to Faust.

pip install -U -r requirements/test.txt into the system Python dies while building opentracing:

AttributeError: install_layout

opentracing 2.4.0 is the latest release and publishes no wheel, so pip builds it from the sdist through the legacy setup.py path, using whatever setuptools is already installed. Debian's packaged python3-setuptools patches its install_lib command to read an install_layout option off the install command it runs against — and that command, setuptools' vendored _distutils, doesn't define it:

File ".../dist-packages/setuptools/command/install_lib.py", line 17, in finalize_options
    self.set_undefined_options('install', ('install_layout', 'install_layout'))
File ".../dist-packages/setuptools/_distutils/cmd.py", line 107, in __getattr__
    raise AttributeError(attr)
AttributeError: install_layout

Nothing in the pin can dodge it — 2.4.0 is the newest release and the sdist is all upstream publishes — so this documents it where contributors actually hit it: a note beside the install commands in the contributing guide, plus a pointer in the extras file itself.

CI doesn't see this because actions/setup-python provides an upstream setuptools, not the distro-patched one.

Verification

On Ubuntu 24.04 with the system Python 3.11, against the four setuptools situations a contributor can be in:

setuptools	result
68.1.2, Ubuntu's python3-setuptools	fails with AttributeError: install_layout
79.0.1, from a python -m venv	builds and imports fine
84.0.0, pip install -U setuptools in place	builds and imports fine
any, via pip install --use-pep517	builds and imports fine (isolated build env)

The note recommends the virtualenv and gives the other two as fallbacks.

Also checked that the comment added to requirements/extras/opentracing.txt is harmless: setup.py's own strip_comments() parser drops it, so the faust[opentracing] extra still resolves to ['opentracing>=1.3.0,<=2.4.0'], and tests/unit/test_packaging.py passes. The reStructuredText parses with the same zero errors as master.

No changelog entry — this documents existing behaviour rather than changing any. Happy to add one if you'd rather it were tracked.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.20%. Comparing base (f355329) to head (89def4a).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #789   +/-   ##
=======================================
  Coverage   96.20%   96.20%           
=======================================
  Files         110      110           
  Lines       11789    11789           
  Branches     1281     1281           
=======================================
  Hits        11342    11342           
  Misses        350      350           
  Partials       97       97           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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