[Tech Debt] Installation doc: wrong Maven version, Python 3.12 mismatch, macOS ARM64 pip failure undocumented #801

linked issues: #766

Search before asking

• I searched in the issues and found nothing similar.

Description

Found during get-started doc verification.

Collection of issues for docs/content/docs/get-started/installation.md:

1. Maven pom.xml example uses flink.version 2.2, which does not exist on Maven Central (line 263) — the example sets <flink.version>2.2</flink.version>, but Maven Central only publishes 2.2.0 (flink-streaming-java:2.2 returns HTTP 404, confirmed by querying repo1.maven.org). Users who copy the example verbatim will get a dependency-resolution failure. Should be <flink.version>2.2.0</flink.version>.

2. install.sh rejects Python 3.12, but Prerequisites lists it as supported (line 39 vs tools/install.sh line 1579) — the documentation states "Python 3.10, 3.11, or 3.12", but install.sh's validate_python_bin function uses py_minor -ge 12 which rejects Python 3.12+. Users with Python 3.12 following the Quick Install path will be told no compatible Python was found.

3. macOS ARM64: pip install apache-flink fails on all installation paths, undocumented (line 62-68 Quick Install, line 137 Manual Install) — apache-beam (a transitive dependency of apache-flink) publishes no macOS ARM64 wheels for any Python version (3.9-3.12; all macOS wheels are x86_64-only). On Apple Silicon, pip falls back to building from source, but pip's PEP 517 build-isolation environment downloads the latest setuptools>=82 which removed pkg_resources, causing the build to fail. The project's own setuptools<82 constraint in pyproject.toml (PR #526, issue #529) only governs flink-agents' runtime dependencies and does not affect the isolated build environment for apache-beam. I tried the commandpip install "setuptools<71" && pip install --no-build-isolation apache-flink==2.2.0 to fix it.

Where to fix

docs/content/docs/get-started/installation.md.

Version and environment

Flink Agents 0.3.0 (main), macOS ARM64 (Apple Silicon), Python 3.11.15 / 3.12.13.

Are you willing to submit a PR?

• I'm willing to submit a PR!