[rush] Design proposal: push notifications to users through CLI

[g-chao]

Maintainers: @octogonz, @g-chao

Summary

We want to have a mechanism to let Monorepo maintainers be able to push notifications during users' day to day development activities.

Problem

As the Monorepo maintainer team, we need to perform upgrades like Node.js, PNPM, etc, and promote new features like Sparo to end users. Besides the regular notification channel, like messages and e-mails, can we push these nofications to users' CLI command activities?

An example

...
Rush install finished successfully. (4.85 seconds)
+----------------------------------------------------+
| NOTICE FROM WEB ARCH: NODE.JS UPGRADE              |
| This Thursday we will block all pipelines that     |
| are still using Node 18.  See this doc for details |
| https://example-wiki.com/2024-01-01-migration.     |
+----------------------------------------------------+

Feature requirements

1. Automatically suppress after some time

• once per day?
• maximum # of times to show it?
• configurable for different messages

2. "Snooze" command, don't bother me for 1 day

• A way to acknowledge one notice:

| are still using Node 16.  See this doc for details |
| https://example-wiki.com/2024-01-01-migration.     |
+----------------------------------------------------+
To stop seeing this event, run "rush alert snooze"

3. Some events have start/end time. (e.g. migration is over after Thursday, whereas Sparo warning lasts forever)
4. Hierarchy of priority, only show most important event?

Implementation

Where are the notices stored?

Option 1: Node.js service / cloud CDN It requires additional effort to implement the service.

Option 2: NPM package (latest version of package, install tarball) Creating new alerts involves NPM publishing which can be cumbersome, also you need a private registry (e.g GitHub projects usually don't have one)

Option 3: Store in a Git branch in the same repo How do we fetch the data?

Where store state?

Rush global temp folder: ~/.rush/notices-state.json

Workflow

1. When users execute a rush command, a separate process to check if the notices-state.json is up to date. Let's say we go with option 3 mentioned in the above section. 1.1 We need to define a way to let users config the notice settings, we can put this configuration under common/config/rush/rush-notices.json Here is an example:

{
  "notices": [
    {
      "title": "Node.js upgrade",
      "details": "This Thursday we will block all pipelines that are still using Node 16.",
      "detailsUrl": "https://example-wiki.com/2024-01-01-migration",
      "condition": "path/to/the/condition/script",
      "startTime": "2024-01-07 11:59pm PST",
      "endTime": "2024-02-07 11:59pm PST"
    },
    {
      "title": "You didn't use Sparo",
      "details": "This repository recommends using Sparo",
      "detailsUrl": "https://example-wiki.com/sparo-benefits",
      "condition": "path/to/the/condition/script",
      "startTime": "2024-01-07 11:59pm PST",
      "endTime": "2025-05-07 11:59pm PST"
    }
  ]
}

1.2 Rush process read the notices config, process them based on repo's situation and save the final state to the Rush temp folder, we can call it common/temp/notices-state.json . Here is an example:

{
  "notices": [
    {
      "title": "Node.js upgrade",
      "details": "This Thursday we will block all pipelines that are still using Node 16.",
      "detailsUrl": "https://example-wiki.com/2024-01-01-migration"
    }
    {
      "title": "You didn't use Sparo",
      "details": "This repository recommends using Sparo",
      "detailsUrl": "https://example-wiki.com/sparo-benefits",
    }
  ]
}

2. When users execute the next rush command, print the notifications if ~/.rush/notices-state.json has any notices there