[rush] Prototype for Rush alerts feature

[g-chao]

Summary

A prototype for Rush alerts feature. Learn more about background of this feature: https://github.com/microsoft/rushstack/issues/4782

In this PR, we presents a MVP for this feature, and explains the idea, flow and how end users can use this feature.

Any feedback is welcome here.

Details

MVP demo

I created a sample repo to demo this feature. To try the MVP demo:

1. Git clone the sample repo, and checkout rush-alerts-demo branch
2. Run rush commands using the rush version in this PR
3. Run any rush commands in CLI to see the alerts configured for the sample repo 3.1 Run rush commands first time, nothing showing in the CLI. 3.2 Run rush commands afterwards, it will print out alerts like below:

Rush install finished successfully. (4.01 seconds)
+-------------------------------------------------------------------------+
| Node.js upgrade                                                         |
| This Thursday we will block all pipelines that are still using Node 16. |
| https://example-wiki.com/2024-01-01-migration                           |
+-------------------------------------------------------------------------+
+-----------------------------------------+
| You didn't use Sparo                    |
| This repository recommends using Sparo  |
| https://example-wiki.com/sparo-benefits |
+-----------------------------------------+

Flow explanation

To use this feature, users need to turn on enablePushRushAlertsToEndUsersInCLI in experiments.json.

Generally there are two stages in this feature:

1. A way let users to configure the rush alerts settings, so that rush engine can retrieve and process the rush alerts data
2. Rush engine reads the alerts data and print out the alerts in CLI

For step 1, we mentioned several ways to achieve it in the design proposal https://github.com/microsoft/rushstack/issues/4782. In this MVP, we chose to store alerts config in a Git branch to prove the idea. From users perspective, they need to config the alerts data under common/config/rush/alerts-config.json. Here is an example of alerts-config.json:

{
  "alerts": [
    {
      "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",
      "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",
      /*
      * If your alerts are depends on the some users' settings, 
      * then you can supply a script here.
      * the script will includes a function 
      * which can we called to determine if the alerts are applicable to certain users
      */
      "condition": "scripts/isSparoEnabled.js",
      "startTime": "2024-01-07 11:59pm PST",
      "endTime": "2025-05-07 11:59pm PST"
    }
  ]
}

Now, when rush engine execute any commands, it will read this config and process the logic there and output the final alerts-state.json under common/temp folder. Here is an example of alerts-state.json:

{
  "lastUpdateTime": "Sun Jun 23 2024 15:35:29 GMT-0700 (Pacific Daylight Time)",
  "alerts": [
    {
      "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"
    }
  ]
}

You might notice that alerts-config.json and alerts-state.json are pretty similar, however, their purpose is different. alerts-config.json is intent to be used by users to config the rush alerts feature behavior and supply the alerts data. alerts-state.json is used by rush internally to keep track the state of rush alerts, also to support more advance features in the later milestones.

For step 2, whenever execute any rush commands, if there is data in `alerts-state.json, print out the alerts in CLI.

Future milestones

1. Support more ways to supply alerts data. Can we offload the whole retrieve alerts data logic to a plugin? So that users can implement their own logic. It is convenient for companies which already have some configuration service.
2. Offload the retrieve data logic to a sperate process, don't block users' actions.
3. Customize the print alerts behavior, such as to limit how many alerts can be printed during a day, to let users mute the notifications for a period of time, etc.

How it was tested

Not yet implemented

Impacted documentation

To be continued