Clarify Flower example version compatibility

[holgerroth]

Summary

• update hello-flower dependencies to use the repo's nvflare~=2.8.0rc convention with Flower 1.26+
• add warnings to the hello-flower docs/README explaining that released NVFlare 2.7.x must use flwr>=1.16,<1.26
• clarify that Flower 1.26+ dynamic SuperLink ports are handled by NVFlare's job-scoped FLWR_HOME config, not by a user-global ~/.flwr/config.toml workaround

Why

A customer followed the main-branch hello-flower guidance with nvflare==2.7.2 and flwr==1.27.0. That released NVFlare version still uses Flower's legacy --federation-config CLI option, which Flower 1.26+ ignores, so the job aborts during flwr list/stop status checks. Main already has the Flower 1.26+ configuration-flow fix, but the public guidance was pointing users at an incompatible released version pair.

Validation

• git diff --check
• python3 ci/check_relative_doc_links.py examples/hello-world/hello-flower/README.md
• python3 -m pytest tests/ci/test_check_relative_doc_links.py -q
• python3 -c 'import tomllib; tomllib.load(open("examples/hello-world/hello-flower/flwr-pt/pyproject.toml", "rb")); tomllib.load(open("examples/hello-world/hello-flower/flwr-pt-tb/pyproject.toml", "rb"))'
• ./build_doc.sh --html --skip-api (succeeded; existing unrelated warnings remain)

[greptile-apps]

Greptile Summary

This PR fixes a real user-facing compatibility trap: main-branch hello-flower docs were pointing users at released NVFlare 2.7.x alongside Flower 1.26+, a combination where the legacy --federation-config CLI option is silently ignored and jobs abort. The fix updates all version pins and adds clear version-split warnings across every relevant doc surface.

• Version pins aligned: requirements.txt and both pyproject.toml files now specify nvflare~=2.8.0rc, matching the tested nvflare==2.8.0rc1 / flwr==1.27.0 combination; the old ~=2.6.0rc (pyproject) and ~=2.7.2rc (requirements) pins are gone.
• Warnings added in four places: README.md (GitHub callout), index.rst (RST warning directive), flower_job_structure.rst (RST note), and flower_run_as_flare_job.rst all now tell 2.7.x users to switch to the 2.7 branch and cap Flower at <1.26.
• Workaround anti-pattern documented: flower_run_as_flare_job.rst explicitly warns against creating a global ~/.flwr/config.toml and explains that NVFlare 2.8 handles dynamic SuperLink port config via a job-scoped $FLWR_HOME/config.toml.

Confidence Score: 5/5

Safe to merge — purely documentation and example dependency updates with no runtime code changes.

All seven changed files are documentation (RST/Markdown) or example dependency manifests (pyproject.toml, requirements.txt). The version pins are internally consistent across all three dependency files, the warning text is accurate and matches the PR description, and the existing repo convention for ~=2.8.0rc pre-release specifiers is correctly applied.

No files require special attention.

Important Files Changed

Filename	Overview
examples/hello-world/hello-flower/requirements.txt	Updated nvflare pin from ~=2.7.2rc to ~=2.8.0rc to align with the Flower 1.26+ compatibility requirement
examples/hello-world/hello-flower/flwr-pt/pyproject.toml	Bumped nvflare dependency from ~=2.6.0rc to ~=2.8.0rc and updated tested-with comment to nvflare==2.8.0rc1
examples/hello-world/hello-flower/flwr-pt-tb/pyproject.toml	Same nvflare version bump as flwr-pt/pyproject.toml; both files are now consistent with each other
examples/hello-world/hello-flower/README.md	Added GitHub-flavored IMPORTANT callout block explaining 2.7.x vs 2.8.x version split; trailing-newline fix included
docs/hello-world/hello-flower/index.rst	Added RST warning directive mirroring the README callout, plus a trailing-newline fix
docs/user_guide/data_scientist_guide/flower_integration/flower_job_structure.rst	Updated embedded pyproject.toml snippet to nvflare~=2.8.0rc and added a note clarifying the 2.7.x/2.8.x version split
docs/user_guide/data_scientist_guide/flower_integration/flower_run_as_flare_job.rst	Updated prose to name the 2.8 RC line explicitly, added 2.7.x fallback guidance, and warned against using a global ~/.flwr/config.toml workaround

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User installs hello-flower] --> B{NVFlare version?}
    B -->|"nvflare~=2.8.0rc (main branch)"| C["flwr>=1.26 ✓"]
    B -->|"nvflare==2.7.x (released)"| D["Switch to 2.7 branch\nflwr>=1.16,<1.26 ✓"]
    C --> E[NVFlare writes job-scoped\n$FLWR_HOME/config.toml\nwith dynamic SuperLink port]
    D --> F["--federation-config CLI\nlegacy Flower path"]
    E --> G[flwr run / list / stop\nwork correctly]
    F --> H["Flower 1.26+ ignores\n--federation-config\n❌ Job aborts"]

Loading

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into codex/flower-co..." | Re-trigger Greptile}

[holgerroth]

/build