[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

[octogonz]

We should standardize the name of the feature:

• Rush alerts 👈 maybe I prefer this one?
• Rush announcements
• Rush notices
• Rush bulletins
• Rush messages

As far as retrieving the latest messages, the main requirements are:

• Even if the user is working on an old branch, Rush should be able to print the latest messages
• Retrieving messages should not require any extra user credentials beyond existing auth for git clone and rush install
• This feature should be very easy for repo maintainers to enable; ideally they shouldn't have to deploy a Node.js, or have a private registry, or author a plugin

Based on these requirements, I am leaning towards a model where the data is stored in the Git main branch. For a huge monorepo, git fetch and git clone can be very expensive operations. But we can work around that by doing a lightweight clone of just the required files in a temporary directory, for example:

# shallow clone + treeless partial clone + no checkout
# (in our huge monorepo, this takes 6 seconds)
git clone  --filter=tree:0 --depth=1 --branch=master --no-checkout https://example.com/my-monorepo.git

cd my-monorepo

# sparse checkout
git config core.sparseCheckout true
echo common/config/rush/ > .git/info/sparse-checkout

# Skip LFS
GIT_LFS_SKIP_SMUDGE=1 git checkout main

[octogonz]

Initial implementation here: https://github.com/microsoft/rushstack/pull/4801

[chengcyber]

This feature should be very easy for repo maintainers to enable; ideally they shouldn't have to deploy a Node.js, or have a private registry, or author a plugin

Would it better to implement this feature with rush plugin? And Rush can provide (or build-in) a rush plugin implementation with the git repo fashion. IMHO, it could provide a more extendibility for advance users. At the same time, new users can also use it in a few steps with the official rush plugin.

By using rush plugin, I am pointing to that Rush can accept different way to get the notice events data by different rush plugins.

As this diagram shows, the majority logic of rush alert controlled by Rush, but the rush plugin plays a vital role to provide a more flexible way to get the notice data remotely.