Deprecating a version of C-PAC¶
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.
To semiautomatically deprecate a published version of C-PAC, follow these steps:
Write a
CRITICAL ALERT
(e.g., “Critical Alert for fMRIPrep-Options in C-PAC v1.8.1 - v1.8.3”) describing the need for the deprecation, the affected versions, and any recommendations.Include that
CRITICAL ALERT
in the GitHub release notes for new version (e.g.,C-PAC/releases/v.1.8.4
“C-PAC Version 1.8.4 Beta”).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 todocker push
.If you aren’t already logged into Docker Hub,
docker login
.In a local clone or copy of
CPAC-Development
:Replace the critical alert in
CRITICAL_ALERT.rst
with theCRITICAL_ALERT
from step one, above.Update
cpac_pipeline.py
andrun.py
:Overwrite the current versions in the
CPAC-Development/deprecate
with the versions from the source code of the version of C-PAC to deprecate.Add
shutil.copyfile('/CRITICAL_ALERT.rst', os.path.join(log_dir, 'CRITICAL_ALERT.rst'))
to
cpac_pipeline.py
afterif not os.path.exists(log_dir): os.makedirs(os.path.join(log_dir))
(e.g.,
cpac_pipeline.py#L264-L265@6cd6c67
) and make sureshutil
is imported before calling that library.Also in
cpac_pipeline.py
, update the variableexecution_info
to include{critical_alert}
at the end, likecpac_pipeline.py#L370@6cd6c67
:execution_info = """ End of subject workflow {workflow} CPAC run complete: Pipeline configuration: {pipeline} Subject workflow: {workflow} Elapsed run time (minutes): {elapsed} Timing information saved in {log_dir}/cpac_individual_timing_{pipeline}.csv System time of start: {run_start} System time of completion: {run_finish} {critical_alert} """
Note
There are probably at least two definitions of
execution_info
that need{critical_alert}
appended to them (e.g.,cpac_pipeline.py#L706@6cd6c67
).Also in
cpac_pipeline.py
, definecritical_alert
based on theCRITICAL_ALERT.rst
file you already updated (e.g.,cpac_pipeline.py#L373-L376@6cd6c67
):with open('/CRITICAL_ALERT.rst', 'r') as critical_alert_file: critical_alert = '\n'.join([ f' {line.rstrip()}' for line in critical_alert_file.readlines()])
Also in
cpac_pipeline.py
, update any calls toexecution_info.format()
to populate the string variable{critical_alert}
with thecritical_alert
you defined above (e.g.,cpac_pipeline.py#L723@6cd6c67
):logger.info(execution_info.format( workflow=workflow.name, pipeline=c.pipeline_setup['pipeline_name'], log_dir=c.pipeline_setup['log_directory']['path'], elapsed=(time.time() - pipeline_start_time) / 60, run_start=pipeline_start_datetime, run_finish=strftime("%Y-%m-%d %H:%M:%S"), critical_alert=critical_alert ))
In
run.py
, print the contents ofCRITICAL_ALERT.rst
, e.g.run.py#L216-L220@6cd6c67
:with open('/CRITICAL_ALERT.rst', 'r') as critical_alert_file: critical_alert = ''.join([line for line in critical_alert_file.readlines() if not line.startswith('.. ')]) print(critical_alert)
From the
deprecate
subdirectory, run./build_and_deprecate ${DEPRECATED_TAG} ${RECOMMENDED_MINIMUM_VERSION}
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 fcpindi/c-pac Tags | Docker Hub for all C-PAC tags currently published on Docker Hub.${RECOMMENDED_MINIMUM_VERSION}
is the semver without any leadingv
. For examplefor each TAG in "" -lite -ABCD-HCP -fMRIPrep-LTS do ./build_and_deprecate release-v1.8.1$TAG 1.8.4 done
to deprecate all variants of C-PAC v1.8.1 with recommended mimumum version v1.8.4.
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.,./rebuild_and_deprecate release-v1.8.1-lite 1.8.4
to update the critical alert for
release-v1.8.1-lite
andrelease-v1.8.1-DEPRECATED
).
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.,
C-PAC/releases/v.1.8.1
“C-PAC Version 1.8.1 Beta”).Trigger a rebuild of this documentation for the new version of C-PAC.