| Title | Add Channel Notices to conda |
| Status | Accepted |
| Author(s) | Travis Hathaway <thathaway@anaconda.com> |
| Created | Apr 21, 2022 |
| Updated | Aug 21, 2022 |
| Discussion | conda#19 |
| Implementation | conda/conda#11462 |
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
The specification is described below via a question-answer format.
The notification message will appear while running the following commands:
createenv createenv updateinstallupdate
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
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
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.
{
"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 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:
# Zero messages will be displayed while running commands such as "install", "update", etc.
number_channel_notices: 0The 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.
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.
We do not expect any backwards compatibility issues for this new feature.
- 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
condato 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.
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
Pull request to the full implementation:
Please add any implementation related suggestions for improvements to this pull request.
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.
Users will automatically be opted in to these feature. They will have the ability to turn it off via a configuration parameter.
This was a standard, non-timed-out vote.
- Among Steering Council members there are 15 "yes", 0 "no", and no abstentions.
- No Emeritus Steering member voted.
This vote has reached quorum (15 + 0 = 15 which is at least 60% of 21).
It has also passed since it recorded 15 "yes" votes and 0 "no" votes giving 15/15 which is greater than 60% of 15.
It should be noted that multiple requests for change were recorded in the pull request about minor implementation details that do not invalidate the previous votes. The author made the requested change.
All CEPs are explicitly CC0 1.0 Universal.