Skip to content

Commit ceb7c89

Browse files
sgiavasissgiavasis
authored
Merge pull request #290 from FCP-INDI/docs/DEPRECATE
📝 Document deprecating a version of C-PAC
2 parents 47fa50f + bc00a12 commit ceb7c89

File tree

7 files changed

+232
-5
lines changed

7 files changed

+232
-5
lines changed

‎docs/_sources/conf.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -573,14 +573,24 @@ def _unireplace(release_note, unireplace):
573573
# How to display URL addresses: 'footnote', 'no', or 'inline'.
574574
# texinfo_show_urls = 'footnote'
575575

576+
rst_prolog = """
577+
578+
.. |version as code| replace:: ``{version}``
579+
580+
""".format(
581+
version=f'v{version}' if not version.endswith('dev') else 'nightly'
582+
)
583+
576584
rst_epilog = """
577585
586+
578587
.. |Versions| replace:: {versions}
579588
580589
""".format(
581590
versions=', '.join(gh_tags[:5])
582591
) if len(gh_tags) >= 5 else ""
583592

593+
584594
def setup(app):
585595
from CPAC.utils.monitoring import custom_logging
586596

‎docs/_sources/developer/deprecating.rst‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
Deprecating a version of C-PAC
2+
==============================
3+
4+
In the rare occasion that a version of C-PAC needs to be deprecated, we add |CRITICAL_ALERT.rst| as a runtime warning and rename the deprecated image tag to ``${DEPRECATED_TAG}-DEPRECATED`` and replace the original tag for the deprecated image with an image that only displays |CRITICAL_ALERT.rst|_. For example, ``fcpindi/c-pac:release-v1.8.1-DEPRECATED`` is the tag that would be needed to run v1.8.1 after v1.8.1 was deprecated.
5+
6+
To semiautomatically deprecate a published version of C-PAC, follow these steps:
7+
8+
#. Write a ``CRITICAL ALERT`` (e.g., |CRITICAL ALERT 1.8.4|_) describing the need for the deprecation, the affected versions, and any recommendations.
9+
#. Include that ``CRITICAL ALERT`` in the GitHub release notes for new version (e.g., |1.8.4 release notes|_).
10+
#. Use |CPAC-Development/deprecate|_ to deprecate the affected version images on Docker Hub. This process requires adequate permissions in the `fcp-indi organization on Docker Hub <https://hub.docker.com/orgs/fcpindi>`_ to ``docker push``.
11+
12+
#. If you aren't already logged into Docker Hub, ``docker login``.
13+
14+
In a local clone or copy of |CPAC-Development|_:
15+
16+
#. Replace the critical alert in |CRITICAL_ALERT.rst|_ with the ``CRITICAL_ALERT`` from step one, above.
17+
#. Update |cpac_pipeline.py|_ and |run.py|_:
18+
19+
#. Overwrite the current versions in the |CPAC-Development/deprecate|_ with the versions from the source code of the version of C-PAC to deprecate.
20+
#. Add
21+
22+
.. code:: Python
23+
24+
shutil.copyfile('/CRITICAL_ALERT.rst',
25+
os.path.join(log_dir, 'CRITICAL_ALERT.rst'))
26+
27+
to |cpac_pipeline.py|_ after
28+
29+
.. code:: Python
30+
31+
if not os.path.exists(log_dir):
32+
os.makedirs(os.path.join(log_dir))
33+
34+
(e.g., |cpac_pipeline.py example 1|_) and make sure ``shutil`` is imported before calling that library.
35+
36+
#. Also in |cpac_pipeline.py|_, update the variable ``execution_info`` to include ``{critical_alert}`` at the end, like |cpac_pipeline.py example 2|_:
37+
38+
.. code:: Python
39+
40+
execution_info = """
41+
42+
End of subject workflow {workflow}
43+
44+
CPAC run complete:
45+
46+
Pipeline configuration: {pipeline}
47+
Subject workflow: {workflow}
48+
Elapsed run time (minutes): {elapsed}
49+
Timing information saved in {log_dir}/cpac_individual_timing_{pipeline}.csv
50+
System time of start: {run_start}
51+
System time of completion: {run_finish}
52+
53+
{critical_alert}
54+
"""
55+
56+
.. note::
57+
58+
There are probably at least two definitions of ``execution_info`` that need ``{critical_alert}`` appended to them (e.g., |cpac_pipeline.py example 3|_).
59+
60+
#. Also in |cpac_pipeline.py|_, define ``critical_alert`` based on the |CRITICAL_ALERT.rst|_ file you already updated (e.g., |cpac_pipeline.py example 4|_):
61+
62+
.. code:: Python
63+
64+
with open('/CRITICAL_ALERT.rst', 'r') as critical_alert_file:
65+
critical_alert = '\n'.join([
66+
f' {line.rstrip()}' for line in critical_alert_file.readlines()])
67+
68+
#. Also in |cpac_pipeline.py|_, update any calls to ``execution_info.format()`` to populate the string variable ``{critical_alert}`` with the ``critical_alert`` you defined above (e.g., |cpac_pipeline.py example 5|_):
69+
70+
.. code:: Python
71+
72+
logger.info(execution_info.format(
73+
workflow=workflow.name,
74+
pipeline=c.pipeline_setup['pipeline_name'],
75+
log_dir=c.pipeline_setup['log_directory']['path'],
76+
elapsed=(time.time() - pipeline_start_time) / 60,
77+
run_start=pipeline_start_datetime,
78+
run_finish=strftime("%Y-%m-%d %H:%M:%S"),
79+
critical_alert=critical_alert
80+
))
81+
82+
#. In |run.py|_, print the contents of |CRITICAL_ALERT.rst|_, e.g. |run.py example 1|_:
83+
84+
.. code:: Python
85+
86+
with open('/CRITICAL_ALERT.rst', 'r') as critical_alert_file:
87+
critical_alert = ''.join([line for line in
88+
critical_alert_file.readlines() if
89+
not line.startswith('.. ')])
90+
print(critical_alert)
91+
92+
#. From the ``deprecate`` subdirectory, run
93+
94+
.. code:: BASH
95+
96+
./build_and_deprecate ${DEPRECATED_TAG} ${RECOMMENDED_MINIMUM_VERSION}
97+
98+
for each tag (as ``${DEPRECATED_TAG}``) that needs to be deprecated. This script will build the replacement images and push them to Docker Hub, overwriting the original image. See |Docker Hub tags|_ for all C-PAC tags currently published on Docker Hub. ``${RECOMMENDED_MINIMUM_VERSION}`` is the |semver| without any leading ``v``. For example
99+
100+
.. code:: BASH
101+
102+
for each TAG in "" -lite -ABCD-HCP -fMRIPrep-LTS
103+
do
104+
./build_and_deprecate release-v1.8.1$TAG 1.8.4
105+
done
106+
107+
to deprecate all variants of C-PAC v1.8.1 with recommended mimumum version v1.8.4.
108+
109+
If the version to be deprecated is already deprecated but the critical alert needs to be updated, that can be done with the same syntax with ``./rebuild_and_deprecate`` (e.g.,
110+
111+
.. code:: BASH
112+
113+
./rebuild_and_deprecate release-v1.8.1-lite 1.8.4
114+
115+
to update the critical alert for ``release-v1.8.1-lite`` and ``release-v1.8.1-DEPRECATED``).
116+
117+
#. Add the critical alert to the release notes of each newly deprecated version, or update the critical alert if one already exists for that version (e.g., |1.8.1 release notes|_).
118+
#. Trigger a rebuild of this documentation for the new version of C-PAC.
119+
120+
.. |1.8.1 release notes| replace:: ``C-PAC/releases/v.1.8.1`` "C-PAC Version 1.8.1 Beta"
121+
122+
.. _1.8.1 release notes: https://github.com/FCP-INDI/C-PAC/releases/tag/v1.8.1
123+
124+
.. |1.8.4 release notes| replace:: ``C-PAC/releases/v.1.8.4`` "C-PAC Version 1.8.4 Beta"
125+
126+
.. _1.8.4 release notes: https://github.com/FCP-INDI/C-PAC/releases/tag/v1.8.4
127+
128+
.. |CRITICAL ALERT 1.8.4| replace:: "Critical Alert for fMRIPrep-Options in C-PAC v1.8.1 - v1.8.3"
129+
130+
.. _CRITICAL ALERT 1.8.4: https://github.com/FCP-INDI/CPAC-Development/blob/028e792/deprecate/CRITICAL_ALERT.rst#critical-alert-for-fmriprep-options-in-c-pac-v181---v183
131+
132+
.. |CRITICAL_ALERT.rst| replace:: ``CRITICAL_ALERT.rst``
133+
134+
.. _CRITICAL_ALERT.rst: https://github.com/FCP-INDI/CPAC-Development/blob/main/deprecate/CRITICAL_ALERT.rst
135+
136+
.. |CPAC-Development| replace:: ``CPAC-Development``
137+
138+
.. _CPAC-Development: https://github.com/FCP-INDI/CPAC-Development
139+
140+
.. |CPAC-Development/deprecate| replace:: ``CPAC-Development/deprecate``
141+
142+
.. _CPAC-Development/deprecate: https://github.com/FCP-INDI/CPAC-Development/tree/028e7929188df99241e8eea78d20d0fd27dbe509/deprecate
143+
144+
.. |cpac_pipeline.py| replace:: ``cpac_pipeline.py``
145+
146+
.. _cpac_pipeline.py: https://github.com/FCP-INDI/CPAC-Development/blob/DEPRECATE/deprecate/cpac_pipeline.py
147+
148+
.. |cpac_pipeline.py example 1| replace:: ``cpac_pipeline.py#L264-L265@6cd6c67``
149+
150+
.. _cpac_pipeline.py example 1: https://github.com/FCP-INDI/CPAC-Development/blob/6cd6c67/deprecate/cpac_pipeline.py#L264-L265
151+
152+
.. |cpac_pipeline.py example 2| replace:: ``cpac_pipeline.py#L370@6cd6c67``
153+
154+
.. _cpac_pipeline.py example 2: https://github.com/FCP-INDI/CPAC-Development/blob/6cd6c67/deprecate/cpac_pipeline.py#L370
155+
156+
.. |cpac_pipeline.py example 3| replace:: ``cpac_pipeline.py#L706@6cd6c67``
157+
158+
.. _cpac_pipeline.py example 3: https://github.com/FCP-INDI/CPAC-Development/blob/6cd6c67/deprecate/cpac_pipeline.py#L706
159+
160+
.. |cpac_pipeline.py example 4| replace:: ``cpac_pipeline.py#L373-L376@6cd6c67``
161+
162+
.. _cpac_pipeline.py example 4: https://github.com/FCP-INDI/CPAC-Development/blob/6cd6c67/deprecate/cpac_pipeline.py#L373-L376
163+
164+
.. |cpac_pipeline.py example 5| replace:: ``cpac_pipeline.py#L723@6cd6c67``
165+
166+
.. _cpac_pipeline.py example 5: https://github.com/FCP-INDI/CPAC-Development/blob/6cd6c67/deprecate/cpac_pipeline.py#L723
167+
168+
.. |Docker Hub tags| replace:: fcpindi/c-pac Tags | Docker Hub
169+
170+
.. _Docker Hub tags: https://hub.docker.com/repository/docker/fcpindi/c-pac/tags
171+
172+
.. |run.py| replace:: ``run.py``
173+
174+
.. _run.py: https://github.com/FCP-INDI/CPAC-Development/blob/DEPRECATE/deprecate/run.py
175+
176+
.. |run.py example 1| replace:: ``run.py#L216-L220@6cd6c67``
177+
178+
.. _run.py example 1: https://github.com/FCP-INDI/CPAC-Development/blob/6cd6c67/deprecate/run.py#L216-L220
179+
180+
.. |semver| raw:: HTML
181+
182+
<span title="semantic version">semver</span>

‎docs/_sources/developer/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Contents:
2626
xcpqc
2727
testing
2828
continuous_integration
29+
deprecating
2930

3031
Indices and tables
3132
^^^^^^^^^^^^^^^^^^

‎docs/_sources/user/cpac.rst‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ or
2424
2525
cpac upgrade
2626
27-
When downloading/upgrading, the ``--platform``, ``--image``, and ``--tag`` let you specify platform (Docker or Singularity), image (Docker image name or URL to image in repository), and tag (version tag, currently only for Docker repositories), respectively.
27+
When downloading/upgrading, the ``--platform``, ``--image``, and ``--tag`` let you specify platform (Docker or Singularity), image (Docker image name or URL to image in repository), and tag (:doc:`version tag </user/versions>`), respectively.
2828

2929
For example, a development Docker image can be downloaded with
3030

@@ -70,6 +70,8 @@ Usage
7070

7171
You can also specify a container image with an ``--image`` argument, passing an image name (e.g., ``fcpindi/c-pac``) for a Docker image or a filepath (e.g. ``~/singularity_images/C-PAC.sif``) for a Singularity image. You can also specify a ``--tag`` (e.g., ``latest`` or ``nightly``).
7272

73+
.. seealso:: :doc:`/user/versions`
74+
7375
You can also provide a link to an AWS S3 bucket containing a BIDS directory as the data source:
7476

7577
.. code-block:: console
@@ -115,7 +117,3 @@ Note that any of the optional arguments above will over-ride any pipeline settin
115117
* The ``participant_label`` and ``participant_ndx`` arguments allow the user to specify which of the many datasets should be processed, which is useful when parallelizing the run of multiple participants.
116118

117119
* If you want to pass runtime options to your container plaform (Docker or Singularity), you can pass them with ``-o`` or ``--container_options``.
118-
119-
.. rubric:: Footnotes
120-
121-
.. [*] The version restrictions for Singularity are specific to cpac the convenience wrapper. C-PAC itself should :doc:`run on Singularity <singularity>` 2 or 3.

‎docs/_sources/user/docker.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ To start, first pull the image from Docker Hub:
1515
1616
Once this is complete, you can use the ``fcpindi/c-pac:latest`` image tag to invoke runs. The full C-PAC Docker image usage options are shown here, with some specific use cases.
1717

18+
.. seealso:: :doc:`/user/versions`
19+
1820
As a quick example, in order to run the C-PAC Docker container in participant mode, for one participant, using a BIDS dataset stored on your machine or server, and using the Docker image's default pipeline configuration (broken into multiple lines for visual clarity):
1921

2022
.. code-block:: console

‎docs/_sources/user/index.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,3 +113,8 @@ User Guide Index
113113
10. Troubleshoot <help>
114114
11. Release Notes <rnotes>
115115
12. Appendix <appendix>
116+
117+
.. toctree::
118+
:hidden:
119+
120+
versions

‎docs/_sources/user/versions.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
C-PAC versions
2+
==============
3+
4+
See :doc:`Release Notes </user/rnotes>` for information about specific versions of C-PAC. The Docker Hub tags are like ``fcpindi/c-pac:release-${VERSION}${VARIANT}`` where ``${VERSION}`` is either a specific semantic version prefixed with a ``v`` or ``latest`` or ``nightly``, like |example version|
5+
6+
Variants
7+
^^^^^^^^
8+
9+
Primary image
10+
-------------
11+
12+
Non-variant, primary image (no ``${VARIANT}`` or an empty string, e.g. |example version|)
13+
14+
Lite variant
15+
------------
16+
17+
``-lite``, primary image without FreeSurfer for a smaller image for runs that don't need FreeSurfer (e.g., |example version|\ ``-lite``)
18+
19+
ABCD-HCP variant
20+
----------------
21+
22+
``-ABCD-HCP``, image with software dependencies version-matched to `ABCD-HCP BIDS fMRI Pipeline <https://github.com/DCAN-Labs/abcd-hcp-pipeline/blob/e480a8f99534f1b05f37bf44c64827384b69b383/Dockerfile>`_ (e.g., |example version|\ ``-ABCD-HCP``)
23+
24+
fMRIPrep-LTS variant
25+
--------------------
26+
27+
``-fMRIPrep-LTS``, image with software dependencies version-matched to `fMRIPrep LTS <https://reproducibility.stanford.edu/fmriprep-lts#long-term-support-lts>`_ (e.g., |example version|\ ``-fMRIPrep-LTS``)
28+
29+
.. |example version| replace:: ``release-``\ |version as code|

0 commit comments

Comments
 (0)