fix: address code review comments

Author: oesteban

docs/faq_tips_tricks.rst

@@ -126,3 +126,23 @@ A symptomatic output looks like: ::
 
 If you would like to run *fMRIPrep* in parallel on multiple subjects please use
 `this method <https://neurostars.org/t/fmriprep-workaround-for-running-subjects-in-parallel/4449>`__.
+
+
+.. _upgrading:
+
+A new version of *fMRIPrep* has been published, when should I upgrade?
+----------------------------------------------------------------------
+
+We follow a philosophy of releasing very often, although the pace is slowing down
+with the maturation of the software.
+It is very likely that your version gets outdated over the extent of your study.
+If that is the case (an ongoing study), then we discourage changing versions.
+In other words, **the whole dataset should be processed with the same version (and
+same container build if they are being used) of *fMRIPrep*.**
+
+On the other hand, if the project is about to start, then we strongly recommend
+using the latest version of the tool.
+
+In any case, if you can find your release listed as *flagged* in `this file
+of our repo <https://github.com/poldracklab/fmriprep/blob/master/.versions.json>`__,
+then please update as soon as possible.

fmriprep/cli/run.py

@@ -43,7 +43,7 @@ def get_parser():
     from packaging.version import Version
     from ..__about__ import __version__
     from ..workflows.bold.resampling import NONSTANDARD_REFERENCES
-    from ._version import check_latest, is_flagged
+    from .version import check_latest, is_flagged
 
     verstr = 'fmriprep v{}'.format(__version__)
 
@@ -281,10 +281,9 @@ def get_parser():
 
     if latest is not None and currentv < latest:
         print("""\
-WARNING: The current version of fMRIPrep (%s) is outdated.
-Please consider upgrading to the latest version %s.
-Before upgrading, please consider that mixing fMRIPrep versions
-within a single study is strongly discouraged.""" % (
+You are using fMRIPrep-%s, and a newer version of fMRIPrep is available: %s.
+Please check out our documentation about how and when to upgrade:
+https://fmriprep.readthedocs.io/en/latest/faq.html#upgrading""" % (
             __version__, latest), file=sys.stderr)
 
     _blist = is_flagged()

fmriprep/cli/tests/test_run.py

@@ -1,7 +1,7 @@
 """Test CLI."""
 from packaging.version import Version
 import pytest
-from .. import _version
+from .. import version as _version
 from ... import __about__
 from ..run import get_parser
 
@@ -24,10 +24,9 @@ def _mock_check_latest(*args, **kwargs):
     captured = capsys.readouterr().err
 
     msg = """\
-WARNING: The current version of fMRIPrep (%s) is outdated.
-Please consider upgrading to the latest version %s.
-Before upgrading, please consider that mixing fMRIPrep versions
-within a single study is strongly discouraged.""" % (current, latest)
+You are using fMRIPrep-%s, and a newer version of fMRIPrep is available: %s.
+Please check out our documentation about how and when to upgrade:
+https://fmriprep.readthedocs.io/en/latest/faq.html#upgrading""" % (current, latest)
 
     assert (msg in captured) is expectation
 

fmriprep/cli/tests/test_version.py

@@ -3,8 +3,8 @@
 from pathlib import Path
 from packaging.version import Version
 import pytest
-from .. import _version
-from .._version import check_latest, DATE_FMT, requests, is_flagged
+from .. import version as _version
+from ..version import check_latest, DATE_FMT, requests, is_flagged
 
 
 class MockResponse:
@@ -64,6 +64,24 @@ def mock_get(*args, **kwargs):
     assert isinstance(v, Version)
     assert v == Version('1.1.0')
 
+    # Mock timeouts
+    def mock_get(*args, **kwargs):
+        raise requests.exceptions.Timeout
+    monkeypatch.setattr(requests, "get", mock_get)
+
+    cachefile.write_text('|'.join(('1.0.0', cachefile.read_text().split('|')[1])))
+    v = check_latest()
+    assert isinstance(v, Version)
+    assert v == Version('1.0.0')
+
+    cachefile.write_text('2.0.0|20180121')
+    v = check_latest()
+    assert v is None
+
+    cachefile.unlink()
+    v = check_latest()
+    assert v is None
+
 
 @pytest.mark.parametrize(('result', 'code', 'json'), [
     (None, 404, None),

fmriprep/cli/_version.py renamed to fmriprep/cli/version.py

@@ -39,7 +39,7 @@ def check_latest():
         try:
             response = requests.get(url='https://pypi.org/pypi/fmriprep/json', timeout=1.0)
         except Exception:
-            pass
+            response = None
 
         if response and response.status_code == 200:
             versions = [Version(rel) for rel in response.json()['releases'].keys()]
@@ -66,7 +66,7 @@ def is_flagged():
         response = requests.get(url="""\
 https://raw.githubusercontent.com/poldracklab/fmriprep/master/.versions.json""", timeout=1.0)
     except Exception:
-        pass
+        response = None
 
     if response and response.status_code == 200:
         flagged = response.json().get('flagged', {}) or {}