From e7ad778a3fd4a6846104c2cdb79b459b89a216f5 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Mon, 25 Apr 2022 12:51:21 +0200 Subject: [PATCH 01/15] adding first draft of channel notification feature CEP" --- cep-6.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 cep-6.md diff --git a/cep-6.md b/cep-6.md new file mode 100644 index 00000000..c10ce903 --- /dev/null +++ b/cep-6.md @@ -0,0 +1,197 @@ + + + + + + + + +
Title Add Channel Notifications to conda
Status Draft
Author(s) Travis Hathaway <thathaway@anaconda.com>
Created Apr 21, 2022
Updated Aug 21, 2022
Discussion NA
Implementation NA
+ + +## Abstract + +In order to better facilitate better communicate between users of `conda` and channel owners, we wish to +implement a notification feature. +Specifically, this feature will give channel owners the ability to send users a small message (about the size +of a single Twitter post). How often this message displays will be set by channel owners, +and will be displayed for each channel a user is actively using (i.e. everything under "channels" in a +user's `.condarc`). + +The messages may contain but are not limited to the following use cases: + +- News about the latest package additions to the channel +- How to sponsor, volunteer or help out a particular channel +- Warnings about a breach of TOS while using a particular channel +- Status updates about the stability of the channel + + +## Specification + +### When will show this message? + +The notification message will be limited to only appearing on the following commands: + +- `create` +- `env create` +- `install` +- `update` +- `env update` +- `search` + +The reasoning behind this decision is that the above commands all retrieve `repodata.json` from the configured +channels. Simply adding another file request (which is very small and immediately cached) would not add much more +overhead to the execution of these commands. Additionally, these are commands where the user already expects network +traffic to occur, so the requirement for having an active internet connection is assumed. + +Here's an example of how a notification message may appear while running the `conda create` command: + +``` +$ conda create -n geopandas geopandas +Collecting package metadata (repodata.json): done +Solving environment: done + +## Package Plan ## + + environment location: /Users/username/opt/conda_x86_64/envs/geopandas + + added / updated specs: + - geopandas + +... (output truncated) + +Notice [info]: +> Here is a message to the user +> Here is a link they could click: https://example.com/link-name +> To see the message again, run `conda motd` + +``` + +### How else can the user access this message? + +Additionally, because users may wish to see this message on demand, we will add a new sub-command called `motd` +for doing just that. The following are a couple examples to show exactly how it would function: + +**Basic usage:** grabs the MOTD for all current channels: + +``` +$ conda (alerts|motd|notices) + +Channel: defaults + +Notice [info]: +This is a test message. It is not very long, and could have a link to a longer post: +https://example.com/short-link + +Channel: conda-forge + +Notice [info]: +Here is another message. It could have info about the latest happenings or blog posts from conda-forge: +https://conda-forge.org/ +``` + +### What file format will this message have and what will it contain? + +The notification message will be in the JSON file format. This will allow us to not only store the message itself but +also metadata about the message, including information about how often the client should display the message (more on +this in the next section). + +Here's an example of the `notifications.json` file which will be stored alongside files such as `repodata.json` on the +channel servers: + +```json +{ + "notifications": [ + { + "message": "Here is an example message that will be displayed to users", + "level": "info", + "created_at": "2022-05-01 00:00:00", + "show_again": "7 days" + } + ] +} +``` + +### How often will this message appear? + +How often the message appears will be configurable by the channel owners. This will be accomplished by several fields +within the `notifications.json` file itself. They are as follows: + +- **created_at** Lets `conda` know how the old the message is +- **show_again** plain english explanation of when to check for a new message; combining this with the previous field + allows us to know when to refresh our cache. + +The client will also have ultimate say over whether this message is displayed. We will provide clients with a setting +to permanently disable these messages in their `.condarc` files: + +```yaml +display_notifications: false +``` + +## Motivation + +The motivation for this CEP came about as channel owners (Anaconda specifically) needed a way to broadcast messages to +users of their channels. These messages may contain specific notices for particular users (e.g. identified by +IP address) or general messages for the wider audience of a particular channel. + +Additionally, this new notification space can also provide a spot for us to relocate "conda update conda" reminders +to a more visible spot (at the end of command output versus in the middle of the output). On top of this, other channels +can use these notifications as a way to share news with their users or "calls for help" in maintaining their channels. + + +## Rationale + +TBD + +## Backwards Compatibility + +We do not expect any backwards compatibility issues for this new feature. + + +## Alternatives + +- **Show MOTD at the beginning of environment activation** This was deemed a little too intrusive/annoying. +- **Show MOTD at the beginning of command output** Users may miss this if place here, especially for commands + with lots of output + + +## References + +This implementation is similar to the way that `npm` handles version update reminders: + +``` +npm install travishathaway@thath-work-laptop + +up to date, audited 365 packages in 3s + +34 packages are looking for funding + run `npm fund` for details + +5 vulnerabilities (1 moderate, 4 high) + +To address all issues (including breaking changes), run: + npm audit fix --force + +Run `npm audit` for details. +npm notice +npm notice New minor version of npm available! 8.5.5 -> 8.7.0 +npm notice Changelog: https://github.com/npm/cli/releases/tag/v8.7.0 +npm notice Run npm install -g npm@8.7.0 to update! +npm notice +``` + +## Sample Implementation + +*PR Coming soon!* + +## FAQ + +TBD + +## Resolution + +TBD + +## Copyright + +All CEPs are explicitly [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/). From ccf373b44b2246dde3342ad22dce2303c9490db2 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Mon, 25 Apr 2022 19:14:00 +0200 Subject: [PATCH 02/15] fixing typos and wording mistakes --- cep-6.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/cep-6.md b/cep-6.md index c10ce903..938b11fd 100644 --- a/cep-6.md +++ b/cep-6.md @@ -11,10 +11,10 @@ ## Abstract -In order to better facilitate better communicate between users of `conda` and channel owners, we wish to +In order to facilitate better communication between users of `conda` and channel owners, we want to implement a notification feature. Specifically, this feature will give channel owners the ability to send users a small message (about the size -of a single Twitter post). How often this message displays will be set by channel owners, +of a single Twitter post). How often this message displays will be set by channel owners and will be displayed for each channel a user is actively using (i.e. everything under "channels" in a user's `.condarc`). @@ -28,9 +28,11 @@ The messages may contain but are not limited to the following use cases: ## Specification -### When will show this message? +The specification is described below via a question-answer format. -The notification message will be limited to only appearing on the following commands: +### When will this message be shown? + +The notification message will appear while running the following commands: - `create` - `env create` @@ -41,7 +43,7 @@ The notification message will be limited to only appearing on the following comm The reasoning behind this decision is that the above commands all retrieve `repodata.json` from the configured channels. Simply adding another file request (which is very small and immediately cached) would not add much more -overhead to the execution of these commands. Additionally, these are commands where the user already expects network +overhead to the execution of these commands. Additionally, these are commands where our users already expect network traffic to occur, so the requirement for having an active internet connection is assumed. Here's an example of how a notification message may appear while running the `conda create` command: @@ -67,12 +69,13 @@ Notice [info]: ``` -### How else can the user access this message? +### How else can our users access this message? -Additionally, because users may wish to see this message on demand, we will add a new sub-command called `motd` -for doing just that. The following are a couple examples to show exactly how it would function: +Additionally, because our users may wish to see this message on demand, we will add a new sub-command called `motd` or +`notices` or `alerts` (exact name is yet to be determined) The following are a couple examples to show exactly how +it would function: -**Basic usage:** grabs the MOTD for all current channels: +**Basic usage:** grabs notifications for all current channels: ``` $ conda (alerts|motd|notices) @@ -90,7 +93,17 @@ Here is another message. It could have info about the latest happenings or blog https://conda-forge.org/ ``` -### What file format will this message have and what will it contain? +**Show a single channel:** grabs notifications for a single channel: + +``` +$ conda (alerts|motd|notices) -c default + +Notice [info]: +This is a test message. It is not very long, and could have a link to a longer post: +https://example.com/short-link +``` + +### What file format will this message have, and what will it contain? The notification message will be in the JSON file format. This will allow us to not only store the message itself but also metadata about the message, including information about how often the client should display the message (more on @@ -134,7 +147,7 @@ The motivation for this CEP came about as channel owners (Anaconda specifically) users of their channels. These messages may contain specific notices for particular users (e.g. identified by IP address) or general messages for the wider audience of a particular channel. -Additionally, this new notification space can also provide a spot for us to relocate "conda update conda" reminders +Additionally, this new notification space can also provide a place for us to relocate `conda update conda` reminders to a more visible spot (at the end of command output versus in the middle of the output). On top of this, other channels can use these notifications as a way to share news with their users or "calls for help" in maintaining their channels. @@ -151,7 +164,7 @@ We do not expect any backwards compatibility issues for this new feature. ## Alternatives - **Show MOTD at the beginning of environment activation** This was deemed a little too intrusive/annoying. -- **Show MOTD at the beginning of command output** Users may miss this if place here, especially for commands +- **Show MOTD at the beginning of command output** Users may miss this if placed here, especially for commands with lots of output From d472f7bf3ef0d4cebf5edcbba276494dbbf21893 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Tue, 26 Apr 2022 14:35:59 +0200 Subject: [PATCH 03/15] several modifications based on feedback from PR --- cep-6.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/cep-6.md b/cep-6.md index 938b11fd..f4b7d1e0 100644 --- a/cep-6.md +++ b/cep-6.md @@ -78,7 +78,7 @@ it would function: **Basic usage:** grabs notifications for all current channels: ``` -$ conda (alerts|motd|notices) +$ conda alerts Channel: defaults @@ -96,7 +96,7 @@ https://conda-forge.org/ **Show a single channel:** grabs notifications for a single channel: ``` -$ conda (alerts|motd|notices) -c default +$ conda alerts -c default Notice [info]: This is a test message. It is not very long, and could have a link to a longer post: @@ -109,33 +109,38 @@ The notification message will be in the JSON file format. This will allow us to also metadata about the message, including information about how often the client should display the message (more on this in the next section). -Here's an example of the `notifications.json` file which will be stored alongside files such as `repodata.json` on the -channel servers: +Here's an example of the `notifications.json` file which will be stored in the root of the channel directory structure. ```json { "notifications": [ { + "id": "1cd1d8e5-d96c-42d1-9c29-e8120ad80823", "message": "Here is an example message that will be displayed to users", "level": "info", - "created_at": "2022-05-01 00:00:00", - "show_again": "7 days" + "created_at": "2022-04-26T11:50:34+00:00", + "expiry": 604800 } ] } ``` -### How often will this message appear? +Detailed overview of the JSON fields: -How often the message appears will be configurable by the channel owners. This will be accomplished by several fields -within the `notifications.json` file itself. They are as follows: +- **notifications** [Array] holds zero or more notifications that will be displayed to the client. + - **id** [String] unique ID for the message itself. UUIDs are preferred, but there is no required format. + - **message** [String] message that gets displayed to users. + - **level** [String] one of (info|warning|error). These will let our users know the category of the message + and will also allow the client to apply different formatting rules (e.g. text color). + - **created_at** [String] ISO 8601 formatted timestamp showing the creation time of the message. + - **expiry** [Number] a number specifying how long in seconds the message is valid for. -- **created_at** Lets `conda` know how the old the message is -- **show_again** plain english explanation of when to check for a new message; combining this with the previous field - allows us to know when to refresh our cache. +### How often will these messages appear? -The client will also have ultimate say over whether this message is displayed. We will provide clients with a setting -to permanently disable these messages in their `.condarc` files: +How often the messages appears will be configurable by the channel owners and the client. This will be accomplished by +the expiry field in the `notifications.json` file itself, but the client will the have ultimate say over whether this +message is displayed. We will provide clients with a setting to permanently disable these messages in their `.condarc` +files: ```yaml display_notifications: false From 7ff7387f6a498c2390069132f3f315895a672a91 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Tue, 26 Apr 2022 14:42:09 +0200 Subject: [PATCH 04/15] typo --- cep-6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cep-6.md b/cep-6.md index f4b7d1e0..90628ae3 100644 --- a/cep-6.md +++ b/cep-6.md @@ -137,7 +137,7 @@ Detailed overview of the JSON fields: ### How often will these messages appear? -How often the messages appears will be configurable by the channel owners and the client. This will be accomplished by +How often the messages appear will be configurable by the channel owners and the client. This will be accomplished by the expiry field in the `notifications.json` file itself, but the client will the have ultimate say over whether this message is displayed. We will provide clients with a setting to permanently disable these messages in their `.condarc` files: From 270b4d3a1dd92d83d845e775451d63ab7718001f Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Tue, 26 Apr 2022 14:44:52 +0200 Subject: [PATCH 05/15] removing motd language --- cep-6.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/cep-6.md b/cep-6.md index 90628ae3..fe402ad3 100644 --- a/cep-6.md +++ b/cep-6.md @@ -65,15 +65,14 @@ Solving environment: done Notice [info]: > Here is a message to the user > Here is a link they could click: https://example.com/link-name -> To see the message again, run `conda motd` +> To see the message again, run `conda alert` ``` ### How else can our users access this message? -Additionally, because our users may wish to see this message on demand, we will add a new sub-command called `motd` or -`notices` or `alerts` (exact name is yet to be determined) The following are a couple examples to show exactly how -it would function: +Additionally, because our users may wish to see this message on demand, we will add a new sub-command called `alerts`. +The following are a couple examples to show exactly how it would function: **Basic usage:** grabs notifications for all current channels: @@ -161,6 +160,7 @@ can use these notifications as a way to share news with their users or "calls fo TBD + ## Backwards Compatibility We do not expect any backwards compatibility issues for this new feature. @@ -168,8 +168,8 @@ We do not expect any backwards compatibility issues for this new feature. ## Alternatives -- **Show MOTD at the beginning of environment activation** This was deemed a little too intrusive/annoying. -- **Show MOTD at the beginning of command output** Users may miss this if placed here, especially for commands +- **Show notifications at the beginning of environment activation** This was deemed a little too intrusive/annoying. +- **Show notifications at the beginning of command output** Users may miss this if placed here, especially for commands with lots of output From 67896c5d20dddfb7498b9c12dfddc75d99c818b7 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Thu, 28 Apr 2022 13:18:35 +0200 Subject: [PATCH 06/15] Update cep-6.md Co-authored-by: Ken Odegard --- cep-6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cep-6.md b/cep-6.md index fe402ad3..7ac65ca6 100644 --- a/cep-6.md +++ b/cep-6.md @@ -142,7 +142,7 @@ message is displayed. We will provide clients with a setting to permanently disa files: ```yaml -display_notifications: false +display_alerts: false ``` ## Motivation From 0fb04df64105a8363c6b133e61f7b5f071882f84 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Thu, 28 Apr 2022 13:18:52 +0200 Subject: [PATCH 07/15] Update cep-6.md Co-authored-by: Ken Odegard --- cep-6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cep-6.md b/cep-6.md index 7ac65ca6..bbe1b558 100644 --- a/cep-6.md +++ b/cep-6.md @@ -65,7 +65,7 @@ Solving environment: done Notice [info]: > Here is a message to the user > Here is a link they could click: https://example.com/link-name -> To see the message again, run `conda alert` +> To see the message again, run `conda alerts` ``` From 30639b74e41154dcf12a472c69393c72bfacbcab Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Thu, 28 Apr 2022 13:24:56 +0200 Subject: [PATCH 08/15] Apply suggestions from code review Co-authored-by: Jannis Leidel --- cep-6.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/cep-6.md b/cep-6.md index bbe1b558..233047f5 100644 --- a/cep-6.md +++ b/cep-6.md @@ -24,7 +24,7 @@ The messages may contain but are not limited to the following use cases: - How to sponsor, volunteer or help out a particular channel - Warnings about a breach of TOS while using a particular channel - Status updates about the stability of the channel - +- Announcements for planned security releases ## Specification @@ -36,10 +36,10 @@ The notification message will appear while running the following commands: - `create` - `env create` -- `install` -- `update` - `env update` +- `install` - `search` +- `update` The reasoning behind this decision is that the above commands all retrieve `repodata.json` from the configured channels. Simply adding another file request (which is very small and immediately cached) would not add much more @@ -62,7 +62,7 @@ Solving environment: done ... (output truncated) -Notice [info]: +Channel notices (info): > Here is a message to the user > Here is a link they could click: https://example.com/link-name > To see the message again, run `conda alerts` @@ -71,7 +71,7 @@ Notice [info]: ### How else can our users access this message? -Additionally, because our users may wish to see this message on demand, we will add a new sub-command called `alerts`. +Additionally, because our users may wish to see this message on demand, we will add a new sub-command called `notices`. The following are a couple examples to show exactly how it would function: **Basic usage:** grabs notifications for all current channels: @@ -132,7 +132,7 @@ Detailed overview of the JSON fields: - **level** [String] one of (info|warning|error). These will let our users know the category of the message and will also allow the client to apply different formatting rules (e.g. text color). - **created_at** [String] ISO 8601 formatted timestamp showing the creation time of the message. - - **expiry** [Number] a number specifying how long in seconds the message is valid for. + - **expiry** [Number] starting at `created_at`, a number specifying how long in seconds the message is valid for. ### How often will these messages appear? @@ -153,7 +153,7 @@ IP address) or general messages for the wider audience of a particular channel. Additionally, this new notification space can also provide a place for us to relocate `conda update conda` reminders to a more visible spot (at the end of command output versus in the middle of the output). On top of this, other channels -can use these notifications as a way to share news with their users or "calls for help" in maintaining their channels. +can use these notifications as a way to share news with their users or requests for help in maintaining their channels. ## Rationale From 6922b88a91a43485994c68410da632186a88de0f Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Fri, 29 Apr 2022 12:36:54 +0200 Subject: [PATCH 09/15] changes based on PR suggestions --- cep-6.md | 60 ++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 21 deletions(-) diff --git a/cep-6.md b/cep-6.md index 233047f5..9598a214 100644 --- a/cep-6.md +++ b/cep-6.md @@ -1,5 +1,5 @@ - + @@ -63,10 +63,12 @@ Solving environment: done ... (output truncated) Channel notices (info): -> Here is a message to the user -> Here is a link they could click: https://example.com/link-name -> To see the message again, run `conda alerts` + Here is a message to the user + Here is a link they could click: https://example.com/link-name + To see the message again, run `conda notices` + +End of channel notices ``` ### How else can our users access this message? @@ -74,30 +76,30 @@ Channel notices (info): Additionally, because our users may wish to see this message on demand, we will add a new sub-command called `notices`. The following are a couple examples to show exactly how it would function: -**Basic usage:** grabs notifications for all current channels: +**Basic usage:** grabs notices for all current channels: ``` -$ conda alerts +$ conda notices Channel: defaults -Notice [info]: +Notices [info]: This is a test message. It is not very long, and could have a link to a longer post: https://example.com/short-link Channel: conda-forge -Notice [info]: +Notices [info]: Here is another message. It could have info about the latest happenings or blog posts from conda-forge: https://conda-forge.org/ ``` -**Show a single channel:** grabs notifications for a single channel: +**Show a single channel:** grabs notices for a single channel: ``` -$ conda alerts -c default +$ conda notices -c defaults -Notice [info]: +Notices [info]: This is a test message. It is not very long, and could have a link to a longer post: https://example.com/short-link ``` @@ -108,17 +110,18 @@ The notification message will be in the JSON file format. This will allow us to also metadata about the message, including information about how often the client should display the message (more on this in the next section). -Here's an example of the `notifications.json` file which will be stored in the root of the channel directory structure. +Here's an example of the `notices.json` file which will be stored in the root of the channel directory structure. ```json { - "notifications": [ + "notices": [ { "id": "1cd1d8e5-d96c-42d1-9c29-e8120ad80823", "message": "Here is an example message that will be displayed to users", "level": "info", "created_at": "2022-04-26T11:50:34+00:00", - "expiry": 604800 + "expiry": 604800, + "interval": 604800 } ] } @@ -126,23 +129,25 @@ Here's an example of the `notifications.json` file which will be stored in the r Detailed overview of the JSON fields: -- **notifications** [Array] holds zero or more notifications that will be displayed to the client. +- **notices** [Array] holds zero or more notices that will be displayed to the client. - **id** [String] unique ID for the message itself. UUIDs are preferred, but there is no required format. - **message** [String] message that gets displayed to users. - - **level** [String] one of (info|warning|error). These will let our users know the category of the message + - **level** [String] one of (info|warning|critical). These will let our users know the category of the message and will also allow the client to apply different formatting rules (e.g. text color). - **created_at** [String] ISO 8601 formatted timestamp showing the creation time of the message. - **expiry** [Number] starting at `created_at`, a number specifying how long in seconds the message is valid for. + - **interval** [Number] starting from the modified time of a cache file, the time in seconds specifying how often + this is shown to the user. ### How often will these messages appear? How often the messages appear will be configurable by the channel owners and the client. This will be accomplished by -the expiry field in the `notifications.json` file itself, but the client will the have ultimate say over whether this +the expiry field in the `notices.json` file itself, but the client will the have ultimate say over whether this message is displayed. We will provide clients with a setting to permanently disable these messages in their `.condarc` files: ```yaml -display_alerts: false +display_notices: false ``` ## Motivation @@ -153,7 +158,7 @@ IP address) or general messages for the wider audience of a particular channel. Additionally, this new notification space can also provide a place for us to relocate `conda update conda` reminders to a more visible spot (at the end of command output versus in the middle of the output). On top of this, other channels -can use these notifications as a way to share news with their users or requests for help in maintaining their channels. +can use these notices as a way to share news with their users or requests for help in maintaining their channels. ## Rationale @@ -168,9 +173,22 @@ We do not expect any backwards compatibility issues for this new feature. ## Alternatives -- **Show notifications at the beginning of environment activation** This was deemed a little too intrusive/annoying. -- **Show notifications at the beginning of command output** Users may miss this if placed here, especially for commands +- **Show notices at the beginning of environment activation:** This was deemed too intrusive/annoying. +- **Show notices at the beginning of command output:** Users may miss this if placed here, especially for commands with lots of output +- **Message in an HTTP header when retrieving any file from the repository:** This would be a better option for some kinds + of messages, like download rate limiting or other blocks due to abuse, since it could be turned on by a rule in a CDN. + However, this use case is probably better addressed by having a standard way for conda to display errors on the + console from HTTP status codes like 429 (Too Many Requests) and 403 (Forbidden). Additionally, serving custom headers + is challenging unless the repository owner has more control over the web server than is usually given by services + like Github Pages. +- **Add notices to the repodata.json file:** The repodata.json file is already being fetched, so adding some + notices would reduce the number of requests. However, the repodata.json file is way too big already, so it + would require clients to download a fairly large file before even being able to show the notification. +- **Create a generic metadata.json file containing a notices key:** This could be appealing for + creating a space for other kinds of channel metadata, but in order to keep things as simple as possible at the moment + it makes more sense to put these in their own file. Plus, it allows more flexibility for dynamic routing options + to this file if that becomes necessary in the future. ## References From 25dc20b6989b0e8258c7661282d78f6edcb63bec Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Fri, 29 Apr 2022 13:13:42 +0200 Subject: [PATCH 10/15] more suggestions from review --- cep-6.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/cep-6.md b/cep-6.md index 9598a214..3a5ef468 100644 --- a/cep-6.md +++ b/cep-6.md @@ -138,6 +138,10 @@ Detailed overview of the JSON fields: - **expiry** [Number] starting at `created_at`, a number specifying how long in seconds the message is valid for. - **interval** [Number] starting from the modified time of a cache file, the time in seconds specifying how often this is shown to the user. + - **arch** Optional[String] allows messages to be targeted to users of a certain architecture. + - Example value: `win-64`, `linux-64`, etc. + - **conda_version** Optional[String] allows messages to be targeted to users of a certain `conda` version. + - Example value: `4.12.0` ### How often will these messages appear? @@ -178,7 +182,7 @@ We do not expect any backwards compatibility issues for this new feature. with lots of output - **Message in an HTTP header when retrieving any file from the repository:** This would be a better option for some kinds of messages, like download rate limiting or other blocks due to abuse, since it could be turned on by a rule in a CDN. - However, this use case is probably better addressed by having a standard way for conda to display errors on the + However, this use case is probably better addressed by having a standard way for `conda` to display errors on the console from HTTP status codes like 429 (Too Many Requests) and 403 (Forbidden). Additionally, serving custom headers is challenging unless the repository owner has more control over the web server than is usually given by services like Github Pages. From 1eb6aa33d6fc8ba2ec35b61d70eed1b5970e6f15 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Tue, 3 May 2022 11:26:35 +0200 Subject: [PATCH 11/15] Apply suggestions from code review Co-authored-by: Ken Odegard --- cep-6.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/cep-6.md b/cep-6.md index 3a5ef468..e71dff50 100644 --- a/cep-6.md +++ b/cep-6.md @@ -62,7 +62,7 @@ Solving environment: done ... (output truncated) -Channel notices (info): +Channel (defaults) notices [info]: Here is a message to the user Here is a link they could click: https://example.com/link-name @@ -81,15 +81,11 @@ The following are a couple examples to show exactly how it would function: ``` $ conda notices -Channel: defaults - -Notices [info]: +Channel (defaults) notices [info]: This is a test message. It is not very long, and could have a link to a longer post: https://example.com/short-link -Channel: conda-forge - -Notices [info]: +Channel (conda-forge) notices [info]: Here is another message. It could have info about the latest happenings or blog posts from conda-forge: https://conda-forge.org/ ``` @@ -99,7 +95,7 @@ https://conda-forge.org/ ``` $ conda notices -c defaults -Notices [info]: +Channel (defaults) notices [info]: This is a test message. It is not very long, and could have a link to a longer post: https://example.com/short-link ``` From 135f8048f286f6185b2a3eff35c86eb935be84fc Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Tue, 24 May 2022 13:01:08 +0200 Subject: [PATCH 12/15] Updates to CEP This commit changes the CEP to reflect what was ultimately done for the implementation. Key changes: - `interval` has been removed. `expiry` will now be the primary field we use to determine how often messages are shown. - The message output has also changed. - Updates the configuration paramter for how to disable this feature - Adds a couple FAQs --- cep-6.md | 64 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 27 deletions(-) diff --git a/cep-6.md b/cep-6.md index e71dff50..e7385069 100644 --- a/cep-6.md +++ b/cep-6.md @@ -38,7 +38,6 @@ The notification message will appear while running the following commands: - `env create` - `env update` - `install` -- `search` - `update` The reasoning behind this decision is that the above commands all retrieve `repodata.json` from the configured @@ -62,13 +61,12 @@ Solving environment: done ... (output truncated) -Channel (defaults) notices [info]: - Here is a message to the user - Here is a link they could click: https://example.com/link-name - To see the message again, run `conda notices` - -End of channel notices +Channel "defaults" has the following notices: + [info] -- Tue May 10 11:50:34 2022 + This is a test message. It is not very long, and could have a link to a longer post: + https://example.com/short-link + ``` ### How else can our users access this message? @@ -81,13 +79,17 @@ The following are a couple examples to show exactly how it would function: ``` $ conda notices -Channel (defaults) notices [info]: -This is a test message. It is not very long, and could have a link to a longer post: -https://example.com/short-link +Retrieving notices: done + +Channel "defaults" has the following notices: + [info] -- Tue May 10 11:50:34 2022 + This is a test message. It is not very long, and could have a link to a longer post: + https://example.com/short-link -Channel (conda-forge) notices [info]: -Here is another message. It could have info about the latest happenings or blog posts from conda-forge: -https://conda-forge.org/ +Channel "conda-forge" has the following notices: + [info] -- Tue May 10 11:50:34 2022 + Here is another message. It could have info about the latest happenings or blog posts from conda-forge: + https://conda-forge.org/ ``` **Show a single channel:** grabs notices for a single channel: @@ -95,9 +97,10 @@ https://conda-forge.org/ ``` $ conda notices -c defaults -Channel (defaults) notices [info]: -This is a test message. It is not very long, and could have a link to a longer post: -https://example.com/short-link +Channel "defaults" has the following notices: + [info] -- Tue May 10 11:50:34 2022 + This is a test message. It is not very long, and could have a link to a longer post: + https://example.com/short-link ``` ### What file format will this message have, and what will it contain? @@ -117,7 +120,6 @@ Here's an example of the `notices.json` file which will be stored in the root of "level": "info", "created_at": "2022-04-26T11:50:34+00:00", "expiry": 604800, - "interval": 604800 } ] } @@ -132,12 +134,6 @@ Detailed overview of the JSON fields: and will also allow the client to apply different formatting rules (e.g. text color). - **created_at** [String] ISO 8601 formatted timestamp showing the creation time of the message. - **expiry** [Number] starting at `created_at`, a number specifying how long in seconds the message is valid for. - - **interval** [Number] starting from the modified time of a cache file, the time in seconds specifying how often - this is shown to the user. - - **arch** Optional[String] allows messages to be targeted to users of a certain architecture. - - Example value: `win-64`, `linux-64`, etc. - - **conda_version** Optional[String] allows messages to be targeted to users of a certain `conda` version. - - Example value: `4.12.0` ### How often will these messages appear? @@ -147,7 +143,8 @@ message is displayed. We will provide clients with a setting to permanently disa files: ```yaml -display_notices: false +# Zero messages will be displayed while running commands such as "install", "update", etc. +number_channel_notices: 0 ``` ## Motivation @@ -216,13 +213,26 @@ npm notice Run npm install -g npm@8.7.0 to update! npm notice ``` -## Sample Implementation +## Implementation + +Pull request to the full implementation: -*PR Coming soon!* +https://github.com/conda/conda/pull/11462 + +Please add any implementation related suggestions for improvements to this pull request. ## FAQ -TBD +### How often will I see notices? + +Notices will be shown however often channel owners would like. Users will also be able to disable channel +notices completely in order to never see them during normal operation. + +### Is this opt-in or opt-out? + +Users will automatically be opted in to these feature. They will have the ability to turn it off via +a configuration parameter. + ## Resolution From bc305a16b633ef670ac966c0957b9359f8d7b358 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Wed, 1 Jun 2022 12:08:08 +0200 Subject: [PATCH 13/15] adding a couple paragraphs for the rationale section --- cep-6.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/cep-6.md b/cep-6.md index e7385069..6ac0ac8a 100644 --- a/cep-6.md +++ b/cep-6.md @@ -160,7 +160,16 @@ can use these notices as a way to share news with their users or requests for he ## Rationale -TBD +In order to keep this feature as a simple as possible and reduce the number of moving parts, we choose to serve +messages via a flat JSON file on the server. The client is responsible for caching these messages which helps +to reduce the number of HTTP requests that it has to make. In designing such a system, it is our goal to keep +the code complexity to a minimum while still affording as much flexibility as possible. In the future, certain +channels may choose to dynamically serve this JSON file and this specification allows for that. + +The other consideration was keeping these messages to a minimum for our users and allowing them to easily disable +these messages if they do not want to see them while running commands such as "install" or "create". Although +we feel these messages are important for users to see, we also do not want to clutter their terminal output. +Ultimately, this is why we are choosing to turn this on by default but are also providing a way to disable it. ## Backwards Compatibility From 9b6a8466c7b5b7695e5cf90411a5d258db437cc7 Mon Sep 17 00:00:00 2001 From: Travis Hathaway Date: Wed, 15 Jun 2022 13:06:14 +0200 Subject: [PATCH 14/15] updates based on review --- cep-6.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/cep-6.md b/cep-6.md index 6ac0ac8a..450b29bc 100644 --- a/cep-6.md +++ b/cep-6.md @@ -118,8 +118,8 @@ Here's an example of the `notices.json` file which will be stored in the root of "id": "1cd1d8e5-d96c-42d1-9c29-e8120ad80823", "message": "Here is an example message that will be displayed to users", "level": "info", - "created_at": "2022-04-26T11:50:34+00:00", - "expiry": 604800, + "created_at": "2022-04-21T11:50:34+00:00", + "expires_at": "2022-04-22T00:00:00+00:00" } ] } @@ -133,14 +133,16 @@ Detailed overview of the JSON fields: - **level** [String] one of (info|warning|critical). These will let our users know the category of the message and will also allow the client to apply different formatting rules (e.g. text color). - **created_at** [String] ISO 8601 formatted timestamp showing the creation time of the message. - - **expiry** [Number] starting at `created_at`, a number specifying how long in seconds the message is valid for. + - **expires_at** [String] ISO 8601 formatted timestamp showing the expiration time of the message. ### How often will these messages appear? -How often the messages appear will be configurable by the channel owners and the client. This will be accomplished by -the expiry field in the `notices.json` file itself, but the client will the have ultimate say over whether this -message is displayed. We will provide clients with a setting to permanently disable these messages in their `.condarc` -files: +How often these messages appear will be configurable by the channel owners and the client. This will be accomplished by +the `expires_at` field in the `notices.json` file itself. When a message has expired, it will trigger a refresh from the +server at which point it will show new messages if there are any. + +The client will the have ultimate say over whether these messages are displayed. We will provide clients with a setting +to permanently disable these messages in their `.condarc` files: ```yaml # Zero messages will be displayed while running commands such as "install", "update", etc. From 4a472a5734b712f54ed33e7cb74478621e440663 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Mon, 20 Jun 2022 15:44:56 +0200 Subject: [PATCH 15/15] Update status and add resolution. --- cep-6.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/cep-6.md b/cep-6.md index 450b29bc..52ef637d 100644 --- a/cep-6.md +++ b/cep-6.md @@ -1,11 +1,11 @@
Title Add Channel Notifications to conda
Title Add Channel Notices to conda
Status Draft
Author(s) Travis Hathaway <thathaway@anaconda.com>
Created Apr 21, 2022
- + - - + +
Title Add Channel Notices to conda
Status Draft
Status Accepted
Author(s) Travis Hathaway <thathaway@anaconda.com>
Created Apr 21, 2022
Updated Aug 21, 2022
Discussion NA
Implementation NA
Discussion https://github.com/conda-incubator/ceps/pull/19
Implementation https://github.com/conda/conda/pull/11462
@@ -244,10 +244,18 @@ notices completely in order to never see them during normal operation. Users will automatically be opted in to these feature. They will have the ability to turn it off via a configuration parameter. - ## Resolution -TBD +This was a standard, non-timed-out vote. + +- Among [Steering Council members](https://github.com/conda-incubator/governance/blob/69f3ce97b3b3e7001bf6bdece7d544f2dea3a633/steering.csv) there are 15 "yes", 0 "no", and no abstentions. +- No [Emeritus Steering member](https://github.com/conda-incubator/governance/blob/69f3ce97b3b3e7001bf6bdece7d544f2dea3a633/emeritus.csv) voted. + +This vote **has reached quorum** (15 + 0 = 15 which is at least [60%](https://github.com/conda-incubator/governance/tree/69f3ce97b3b3e7001bf6bdece7d544f2dea3a633#enhancement-proposal-approval) of 21). + +It **has also passed** since it recorded 15 "yes" votes and 0 "no" votes giving 15/15 which is greater than [60%](https://github.com/conda-incubator/governance/tree/69f3ce97b3b3e7001bf6bdece7d544f2dea3a633#enhancement-proposal-approval) of 15. + +It should be noted that [multiple](https://github.com/conda-incubator/ceps/pull/19#discussion_r893667925) [requests](https://github.com/conda-incubator/ceps/pull/19#pullrequestreview-1006170777) [for change](https://github.com/conda-incubator/ceps/pull/19#pullrequestreview-1008320119) were recorded in the pull request about minor implementation details that do not invalidate the previous votes. The author [made the requested change](https://github.com/conda-incubator/ceps/pull/19#issuecomment-1156335851). ## Copyright