[tsalo]

Changes proposed in this pull request

check_latest() looked up the latest release on PyPI. XCP-D has never been published there (https://pypi.org/pypi/xcp_d/json returns 404), so the request always failed silently and the "a newer version of XCP-D is available" message never printed.

This PR points check_latest() at the pennlinc/xcp_d image tags on Docker Hub:

• Tags that aren't versions (latest, unstable) and prerelease tags are skipped. The highest remaining version wins.
• It follows the API's next links, up to 5 pages of 100 tags each (there are 77 tags today).
• Docker Hub allows 180 API requests per IP, more than GitHub's 60 per hour for unauthenticated requests. The existing 14-day cache in ~/.cache/xcp_d/latest is unchanged.
• If anything fails (no network, a non-200 status, or an unexpected payload), the function returns None, so the check is skipped as before.

The flagged-version check (is_flagged(), which reads .versions.json from GitHub) already worked and is unchanged.

New unit tests in xcp_d/tests/test_cli_version.py mock requests.get, so they need no network. They cover tag filtering, pagination, failure handling, and the cache. Run against the real API, the lookup returns 26.2.0.

Documentation that should be reviewed

• New docs/faq.rst with an Upgrading section (anchor #upgrading), which the CLI upgrade message already links to (faq.html#upgrading). It explains the two startup checks, when to upgrade (and why not to mix versions mid-study), and how to upgrade with Docker, Apptainer, or pip.
• docs/index.rst: FAQ added to the toctree.

I didn't build the docs locally.

Related PRs

The same change in the other PennLINC BIDS Apps:

• Warn users about newer releases and flagged versions qsiprep#1188: QSIPrep, Docker Hub tags plus .versions.json flagging
• Warn about flagged and outdated versions at runtime qsirecon#407: QSIRecon, Docker Hub tags plus .versions.json flagging
• Check for new releases against Docker Hub tags instead of PyPI aslprep#733: ASLPrep, Docker Hub tags

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.15385% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 83.42%. Comparing base (5c12e17) to head (223ec3f).

Files with missing lines	Patch %	Lines
xcp_d/cli/version.py	96.15%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1639      +/-   ##
==========================================
+ Coverage   83.19%   83.42%   +0.23%     
==========================================
  Files          58       58              
  Lines        8094     8111      +17     
  Branches     1137     1139       +2     
==========================================
+ Hits         6734     6767      +33     
+ Misses       1014     1000      -14     
+ Partials      346      344       -2     

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.