From 2b40f096d8ff0d9f3db4a47239f5fa275987a8ed Mon Sep 17 00:00:00 2001 From: bcumming Date: Mon, 14 Jul 2025 12:41:37 +0200 Subject: [PATCH 1/7] add deprecation guide for uenv --- docs/software/prgenv/prgenv-gnu.md | 1 + docs/software/uenv/deploy.md | 48 ++++++++++++++++++++++++++---- 2 files changed, 43 insertions(+), 6 deletions(-) diff --git a/docs/software/prgenv/prgenv-gnu.md b/docs/software/prgenv/prgenv-gnu.md index a10d3892..a7e6b4db 100644 --- a/docs/software/prgenv/prgenv-gnu.md +++ b/docs/software/prgenv/prgenv-gnu.md @@ -10,6 +10,7 @@ It is the go to programming environment on all systems and target node types, th The [`linalg`][ref-uenv-linalg] environment is similar to prgenv-gnu, with additional linear algebra and mesh partitioning algorithms. +[](){#ref-uenv-prgenv-gnu-versioning} ## Versioning The naming scheme is `prgenv-gnu/`, where `` has the `YY.M[M]` format, for example November 2024 is `24.11`, and January 2025 would be `25.1`. diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md index 36f2fd5e..f968687e 100644 --- a/docs/software/uenv/deploy.md +++ b/docs/software/uenv/deploy.md @@ -184,18 +184,19 @@ uenv image copy build:: deploy:: # (1)! uenv image copy deploy::prgenv-gnu/24.11:v1@daint%gh200 deploy::prgenv-gny/24.11@santis%gh200 ``` +[](){#ref-uenv-remove} ### Removing a uenv To remove a uenv, you can use the `uenv` command line tool: ```bash -uenv image delete --token=${HOME}/.ssh/jfrog-token deploy:: +uenv image delete --token=${HOME}/.ssh/jfrog-token :: ``` !!! danger - Removing a uenv is disruptive. - Please have a look at out [uenv removal policy][ref-uenv-removal] for more information. + Removing a uenv that has been deployed (i.e. is in the `deploy::` namespace) is potentially disruptive for users. + Please see the [uenv lifecycle][ref-uenv-lifecycle] guide for more information. ## Source code access @@ -226,10 +227,45 @@ Permissions to access restricted resources is set on a per-pipeline basis | `vasp` | `vasp6`, `cscs-uenv-admin` | `uenv-sources/vasp` | VASP requires a paid license to access source | Simon Frasch | | `vmd` | `uenv-sources-csstaff` | `uenv-sources/vmd` | VMD requires an account to download the source code | Alberto Invernizzi | -[](){#ref-uenv-removal} -## Deprecation and removal of uenv +[](){#ref-uenv-lifecycle} +## uenv lifecycle -!!! todo "Finalize and document the deprecation process" +Scientific applications and tools have different release cycles (e.g. annual, quarterly or irregular), and the communities that use them have different expectations (e.g. ML users expect tools released in the last 3 months, while some scientific communities value support for old versions of software). +For this reason, there is not a universal release and deprecation schedule for supported applications and programming environments - how often to release, how long to provide support, and when to remove old versions is up to the maintainer of the uenv, based on their user's requirements and the overheads of maintaining old versions. +While the frequency of updates and deprecation policy is defined by the uenv maintainer, the following release cycle with tag names should be followed when possible: + +- [optional] tag pre-releases with `:rc1`, `:rc2`, etc + - uenv tagged as release candidates are intended for early testing only, and can be removed at any point. + - e.g. `prgenv-gnu/25.6:rc1` is released for users to do early testing and give feedback. +- Tag `:v1` for the first official release. +- [optional] release updated versions of uenv with tags ()`:v2`, `:v3`, ...) with patches and fixes. +- Remove old versions according to a deprecation policy. + +A uenv's release and support policy should be part of the uenv's documentation under the "Versioning" section, see [prgenv-gnu][ref-uenv-prgenv-gnu-versioning] for example. + +The versioning section should provide the following information: + +* the release schedule; +* the support, update and deprecation policy for the uenv; +* details about the currently deployed versions, changelogs and relevant information how to upgrade if appropriate. + +!!! example "Example deprecation policy" + A scientific application `sciapp` is released annually by the developers, and projects using the software on CSCS systems expect support for two years. + + * Release a new version annually and version with the year, for example `sciapp/2025` being the most recent version in 2025. + * CSCS provides full support for the current release, and partial support for old releases: + * `sciapp/2025`: provide updates and fixes with new tags, take feature requests, and respond to questions about usage and how to upgrade to this version. + * `sciapp/2024`: only support the most recent tag and only create new tags to fix breaking changes. + * `sciapp/2023`: provided "as is" for the first quarter of 2025 while users have the chance to upgrade. + * If there is a major breaking change to the system that would require a large effort to continue providing last year's version, and would require users to also update their workflow, we might choose to encourage deprecate early and help users upgrade to the latest version. + +Generally speacking, uenv are removed (deleted from the `deploy::` namespace) under the following circumstances: + +- when they are no longer supported as per the deprecation policy of the uenv; +- when release candidates are superceded by a new release candidate or an official `:v1` release; +- when a new tag of a `name/version` is deployed to replace a "broken" uenv: + - there might have been a critical issue affecting security, correctness or performance that means all users should update. + - _do not_ remove uenv tags that continue to meet the needs of users (e.g. if a new tag was introduced to fix an issue that only affected specific users or use cases). [uenv-sources]: https://jfrog.svc.cscs.ch/artifactory/uenv-sources/ From ecb3286e3c5891f9893feba2e065f6fc9b4f1cde Mon Sep 17 00:00:00 2001 From: bcumming Date: Mon, 14 Jul 2025 13:03:41 +0200 Subject: [PATCH 2/7] fix spelling; add deprecation policy to prgenv-gnu --- docs/software/prgenv/prgenv-gnu.md | 9 +++++++++ docs/software/uenv/deploy.md | 6 +++--- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/software/prgenv/prgenv-gnu.md b/docs/software/prgenv/prgenv-gnu.md index a7e6b4db..02d14e5c 100644 --- a/docs/software/prgenv/prgenv-gnu.md +++ b/docs/software/prgenv/prgenv-gnu.md @@ -23,6 +23,15 @@ The release schedule is not fixed, with new versions will be released roughly ev | 24.11 | a100, gh200, zen2 | daint, eiger, santis, clariden, bristen | | 24.7 | gh200, zen2 | daint, eiger, todi | +### Deprecation policy + +We will provide full support for 12 months after the uenv image is released, and remove the images when they are no longer being used or when system upgrades break their functionality on the system. + +* It is recommended to document how you compiled and set up your workflow using `prgenv-gnu` so that you can recreate it with future versions. +* The 24.7 release is no longer supported and will be removed at the end of July 2025 - users are encouraged to update to 24.11 or later, before requesting support. + +### Versions + === "24.11" The key updates in version 24.11:v1 from the 24.7 version were: diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md index f968687e..81745e5d 100644 --- a/docs/software/uenv/deploy.md +++ b/docs/software/uenv/deploy.md @@ -196,7 +196,7 @@ uenv image delete --token=${HOME}/.ssh/jfrog-token :: !!! danger Removing a uenv that has been deployed (i.e. is in the `deploy::` namespace) is potentially disruptive for users. - Please see the [uenv lifecycle][ref-uenv-lifecycle] guide for more information. + Please see the [uenv life cycle][ref-uenv-lifecycle] guide for more information. ## Source code access @@ -228,7 +228,7 @@ Permissions to access restricted resources is set on a per-pipeline basis | `vmd` | `uenv-sources-csstaff` | `uenv-sources/vmd` | VMD requires an account to download the source code | Alberto Invernizzi | [](){#ref-uenv-lifecycle} -## uenv lifecycle +## uenv life cycle Scientific applications and tools have different release cycles (e.g. annual, quarterly or irregular), and the communities that use them have different expectations (e.g. ML users expect tools released in the last 3 months, while some scientific communities value support for old versions of software). For this reason, there is not a universal release and deprecation schedule for supported applications and programming environments - how often to release, how long to provide support, and when to remove old versions is up to the maintainer of the uenv, based on their user's requirements and the overheads of maintaining old versions. @@ -260,7 +260,7 @@ The versioning section should provide the following information: * `sciapp/2023`: provided "as is" for the first quarter of 2025 while users have the chance to upgrade. * If there is a major breaking change to the system that would require a large effort to continue providing last year's version, and would require users to also update their workflow, we might choose to encourage deprecate early and help users upgrade to the latest version. -Generally speacking, uenv are removed (deleted from the `deploy::` namespace) under the following circumstances: +Generally speaking, uenv are removed (deleted from the `deploy::` namespace) under the following circumstances: - when they are no longer supported as per the deprecation policy of the uenv; - when release candidates are superceded by a new release candidate or an official `:v1` release; From 202a5080a18e4cd40a107134ab5158bdc06608a2 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Mon, 14 Jul 2025 13:04:16 +0200 Subject: [PATCH 3/7] Update docs/software/uenv/deploy.md Co-authored-by: Rocco Meli --- docs/software/uenv/deploy.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md index 81745e5d..d2d9d012 100644 --- a/docs/software/uenv/deploy.md +++ b/docs/software/uenv/deploy.md @@ -237,7 +237,6 @@ While the frequency of updates and deprecation policy is defined by the uenv mai - [optional] tag pre-releases with `:rc1`, `:rc2`, etc - uenv tagged as release candidates are intended for early testing only, and can be removed at any point. - - e.g. `prgenv-gnu/25.6:rc1` is released for users to do early testing and give feedback. - Tag `:v1` for the first official release. - [optional] release updated versions of uenv with tags ()`:v2`, `:v3`, ...) with patches and fixes. - Remove old versions according to a deprecation policy. From 1febde8a513cf8dd978cbae01dd22f8818d4666a Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Mon, 14 Jul 2025 13:04:28 +0200 Subject: [PATCH 4/7] Update docs/software/uenv/deploy.md Co-authored-by: Rocco Meli --- docs/software/uenv/deploy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md index d2d9d012..782a0036 100644 --- a/docs/software/uenv/deploy.md +++ b/docs/software/uenv/deploy.md @@ -238,7 +238,7 @@ While the frequency of updates and deprecation policy is defined by the uenv mai - [optional] tag pre-releases with `:rc1`, `:rc2`, etc - uenv tagged as release candidates are intended for early testing only, and can be removed at any point. - Tag `:v1` for the first official release. -- [optional] release updated versions of uenv with tags ()`:v2`, `:v3`, ...) with patches and fixes. +- [optional] release updated versions of uenv with tags (`:v2`, `:v3`, ...) with patches and fixes. - Remove old versions according to a deprecation policy. A uenv's release and support policy should be part of the uenv's documentation under the "Versioning" section, see [prgenv-gnu][ref-uenv-prgenv-gnu-versioning] for example. From 2ccf228d19d2ac49a3a0c272d0f79f676d43bbd7 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Mon, 14 Jul 2025 13:04:40 +0200 Subject: [PATCH 5/7] Update docs/software/uenv/deploy.md Co-authored-by: Rocco Meli --- docs/software/uenv/deploy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md index 782a0036..fbe4a330 100644 --- a/docs/software/uenv/deploy.md +++ b/docs/software/uenv/deploy.md @@ -241,7 +241,7 @@ While the frequency of updates and deprecation policy is defined by the uenv mai - [optional] release updated versions of uenv with tags (`:v2`, `:v3`, ...) with patches and fixes. - Remove old versions according to a deprecation policy. -A uenv's release and support policy should be part of the uenv's documentation under the "Versioning" section, see [prgenv-gnu][ref-uenv-prgenv-gnu-versioning] for example. +A uenv's release and support policy is part of the uenv's documentation under the "Versioning" section, see [prgenv-gnu][ref-uenv-prgenv-gnu-versioning] for example. The versioning section should provide the following information: From 0dd0c8700d91812b0ff8cd220c27e9cbdb1871f3 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Mon, 14 Jul 2025 13:04:57 +0200 Subject: [PATCH 6/7] Update docs/software/uenv/deploy.md Co-authored-by: Rocco Meli --- docs/software/uenv/deploy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md index fbe4a330..561d29c6 100644 --- a/docs/software/uenv/deploy.md +++ b/docs/software/uenv/deploy.md @@ -249,7 +249,7 @@ The versioning section should provide the following information: * the support, update and deprecation policy for the uenv; * details about the currently deployed versions, changelogs and relevant information how to upgrade if appropriate. -!!! example "Example deprecation policy" +??? example "Example deprecation policy" A scientific application `sciapp` is released annually by the developers, and projects using the software on CSCS systems expect support for two years. * Release a new version annually and version with the year, for example `sciapp/2025` being the most recent version in 2025. From 2e5bc1a1df5d7477bb08c6d21415755f12fb21e6 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Mon, 14 Jul 2025 13:05:30 +0200 Subject: [PATCH 7/7] Update docs/software/uenv/deploy.md Co-authored-by: Rocco Meli --- docs/software/uenv/deploy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/software/uenv/deploy.md b/docs/software/uenv/deploy.md index 561d29c6..14046911 100644 --- a/docs/software/uenv/deploy.md +++ b/docs/software/uenv/deploy.md @@ -264,7 +264,7 @@ Generally speaking, uenv are removed (deleted from the `deploy::` namespace) und - when they are no longer supported as per the deprecation policy of the uenv; - when release candidates are superceded by a new release candidate or an official `:v1` release; - when a new tag of a `name/version` is deployed to replace a "broken" uenv: - - there might have been a critical issue affecting security, correctness or performance that means all users should update. + - there might have been a critical issue affecting security, correctness, or performance that means all users should update. - _do not_ remove uenv tags that continue to meet the needs of users (e.g. if a new tag was introduced to fix an issue that only affected specific users or use cases). [uenv-sources]: https://jfrog.svc.cscs.ch/artifactory/uenv-sources/