diff --git a/cep-6.md b/cep-6.md new file mode 100644 index 00000000..52ef637d --- /dev/null +++ b/cep-6.md @@ -0,0 +1,262 @@ + + + + + + + + +
Title Add Channel Notices to conda
Status Accepted
Author(s) Travis Hathaway <thathaway@anaconda.com>
Created Apr 21, 2022
Updated Aug 21, 2022
Discussion https://github.com/conda-incubator/ceps/pull/19
Implementation https://github.com/conda/conda/pull/11462
+ + +## Abstract + +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 +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 +- Announcements for planned security releases + +## Specification + +The specification is described below via a question-answer format. + +### When will this message be shown? + +The notification message will appear while running the following commands: + +- `create` +- `env create` +- `env update` +- `install` +- `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 +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: + +``` +$ 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) + + +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? + +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 notices for all current channels: + +``` +$ conda notices + +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" 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: + +``` +$ conda notices -c defaults + +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? + +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 `notices.json` file which will be stored in the root of the channel directory structure. + +```json +{ + "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-21T11:50:34+00:00", + "expires_at": "2022-04-22T00:00:00+00:00" + } + ] +} +``` + +Detailed overview of the JSON fields: + +- **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|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. + - **expires_at** [String] ISO 8601 formatted timestamp showing the expiration time of the message. + +### How often will these messages appear? + +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. +number_channel_notices: 0 +``` + +## 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 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 notices as a way to share news with their users or requests for help in maintaining their channels. + + +## Rationale + +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 + +We do not expect any backwards compatibility issues for this new feature. + + +## Alternatives + +- **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 + +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 +``` + +## Implementation + +Pull request to the full implementation: + +https://github.com/conda/conda/pull/11462 + +Please add any implementation related suggestions for improvements to this pull request. + +## FAQ + +### 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 + +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 + +All CEPs are explicitly [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).