[rush] Document rush-alerts.json

websites/rushjs.io/docs/pages/configs/rush-alerts_json.md

@@ -0,0 +1,104 @@
+---
+title: rush-alerts.json (experimental)
+---
+
+This is the template that [rush init](../commands/rush_init.md) generates for the Rush alerts feature.
+
+> **NOTE:** Since this feature is experimental, you must invoke `rush init --include-experiments`.
+
+**common/config/rush/rush-alerts.json**
+
+````js
+/**
+ * This configuration file manages the Rush alerts feature.
+ * More documentation is available on the Rush website: https://rushjs.io
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-alerts.schema.json",
+
+  /**
+   * Settings such as `startTime` and `endTime` will use this timezone.
+   * If omitted, the default timezone is UTC (`+00:00`).
+   */
+  "timezone": "-08:00",
+
+  /**
+   * An array of alert messages and conditions for triggering them.
+   */
+  "alerts": [
+    // {
+    //   /**
+    //    * When the alert is displayed, this title will appear at the top of the message box.
+    //    * It should be a single line of text, as concise as possible.
+    //    */
+    //   "title": "Node.js upgrade soon!",
+    //
+    //   /**
+    //    * When the alert is displayed, this text appears in the message box.  To make the
+    //    * JSON file more readable, if the text is longer than one line, you can instead provide
+    //    * an array of strings that will be concatenated.  Your text may contain newline characters,
+    //    * but generally this is unnecessary because word-wrapping is automatically applied.
+    //    */
+    //   "message": [
+    //     "This Thursday, we will complete the Node.js version upgrade.  Any pipelines that",
+    //     " still have not upgraded will be temporarily disabled."
+    //   ],
+    //
+    //   /**
+    //    * (OPTIONAL) To avoid spamming users, the `title` and `message` settings should be kept
+    //    * as concise as possible.  If you need to provide more detail, use this setting to
+    //    * print a hyperlink to a web page with further guidance.
+    //    */
+    //   // "detailsUrl": "https://contoso.com/team-wiki/2024-01-01-migration",
+    //
+    //   /**
+    //    * (OPTIONAL) If `startTime` is specified, then this alert will not be shown prior to
+    //    * that time.
+    //    *
+    //    * Keep in mind that the alert is not guaranteed to be shown at this time, or at all:
+    //    * Alerts are only displayed after a Rush command has triggered fetching of the
+    //    * latest rush-alerts.json configuration.  Also, display of alerts is throttled to
+    //    * avoid spamming the user with too many messages.  If you need to test your alert,
+    //    * set the environment variable `RUSH_ALERTS_DEBUG=1` to disable throttling.
+    //    *
+    //    * The `startTime` should be specified as `YYYY-MM-DD HH:MM` using 24 hour time format,
+    //    * or else `YYYY-MM-DD` in which case the time part will be `00:00` (start of that day).
+    //    * The time zone is obtained from the `timezone` setting above.
+    //    */
+    //   // "startTime": "2024-01-01 15:00",
+    //
+    //   /**
+    //    * (OPTIONAL) This alert will not be shown if the current time is later than `endTime`.
+    //    * The format is the same as `startTime`.
+    //    */
+    //   // "endTime": "2024-01-05",
+    //
+    //   /**
+    //    * (OPTIONAL) The filename of a script that determines whether this alert can be shown,
+    //    * found in the "common/config/rush/alert-scripts" folder.  The script must define
+    //    * a CommonJS export named `canShowAlert` that returns a boolean value, for example:
+    //    *
+    //    * ```
+    //    * module.exports.canShowAlert = function () {
+    //    *   // (your logic goes here)
+    //    *   return true;
+    //    * }
+    //    * ```
+    //    *
+    //    * Rush will invoke this script with the working directory set to the monorepo root folder,
+    //    * with no guarantee that `rush install` has been run.  To ensure up-to-date alerts, Rush
+    //    * may fetch and checkout the "common/config/rush-alerts" folder in an unpredictable temporary
+    //    * path.  Therefore, your script should avoid importing dependencies from outside its folder,
+    //    * generally be kept as simple and reliable and quick as possible.  For more complex conditions,
+    //    * we suggest to design some other process that prepares a data file or environment variable
+    //    * that can be cheaply checked by your condition script.
+    //    */
+    //   // "conditionScript": "rush-alert-node-upgrade.js"
+    // }
+  ]
+}
+````
+
+## See also
+
+- [rush init](../commands/rush_init.md)

websites/rushjs.io/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/configs/rush-alerts_json.md

@@ -0,0 +1,102 @@
+---
+
+---
+
+## title: rush-alerts.json (实验性)
+
+这是[rush init](../commands/rush_init.md)为 Rush 警报功能生成的模板。
+
+> **注意：** 由于此功能为实验性功能，您必须调用 `rush init --include-experiments`。
+
+**common/config/rush/rush-alerts.json**
+
+````js
+/**
+ * 此配置文件管理Rush警报功能。
+ * 更多文档可在Rush网站上查看：https://rushjs.io
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-alerts.schema.json",
+
+  /**
+   * 设置如 `startTime` 和 `endTime` 将使用此时区。
+   * 如果省略，默认时区为UTC（`+00:00`）。
+   */
+  "timezone": "-08:00",
+
+  /**
+   * 触发它们的警报消息和条件的数组。
+   */
+  "alerts": [
+    // {
+    //   /**
+    //    * 当警报显示时，此标题将出现在消息框的顶部。
+    //    * 应该是一行文字，尽可能简洁。
+    //    */
+    //   "title": "Node.js upgrade soon!",
+    //
+    //   /**
+    //    * 当警报显示时，此文本出现在消息框中。为了使JSON文件更易于阅读，如果文本超过一行，
+    //    * 你可以提供一个字符串数组，这些字符串将被串联。你的文本可能包含换行符，
+    //    * 但通常这是不必要的，因为会自动应用自动换行。
+    //    */
+    //   "message": [
+    //     "This Thursday, we will complete the Node.js version upgrade.  Any pipelines that",
+    //     " still have not upgraded will be temporarily disabled."
+    //   ],
+    //
+    //   /**
+    //    * （可选）为避免对用户进行轰炸，应尽可能保持 `title` 和 `message` 的简洁。
+    //    * 如果需要提供更多细节，使用此设置打印指向具有进一步指导的网页的超链接。
+    //    */
+    //   // "detailsUrl": "https://contoso.com/team-wiki/2024-01-01-migration",
+    //
+    //   /**
+    //    * （可选）如果指定了 `startTime`，则在该时间之前不会显示此警报。
+    //    *
+    //    * 请记住，不能保证在此时间或根本就显示警报：
+    //    * 只有在Rush命令触发了获取最新的rush-alerts.json配置之后才会显示警报。
+    //    * 此外，为避免对用户轰炸太多信息，警报的显示是受到限制的。如果你需要测试你的警报，
+    //    * 设置环境变量 `RUSH_ALERTS_DEBUG=1` 来禁用限制。
+    //    *
+    //    * `startTime` 应指定为 `YYYY-MM-DD HH:MM` 使用24小时格式，
+    //    * 或者 `YYYY-MM-DD` 在这种情况下时间部分将是 `00:00`（那天的开始）。
+    //    * 时区从上面的 `timezone` 设置获取。
+    //    */
+    //   // "startTime": "2024-01-01 15:00",
+    //
+    //   /**
+    //    * （可选）如果当前时间晚于 `endTime`，则不会显示此警报。
+    //    * 格式与 `startTime` 相同。
+    //    */
+    //   // "endTime": "2024-01-05",
+    //
+    //   /**
+    //    * （可选）确定是否可以显示此警报的脚本的文件名，
+    //    * 位于“common/config/rush/alert-scripts”文件夹中。脚本必须定义
+    //    * 一个名为 `canShowAlert` 的CommonJS导出，返回一个布尔值，例如：
+    //    *
+    //    * ```
+    //    * module.exports.canShowAlert = function () {
+    //    *   // （你的逻辑在这里）
+    //    *   return true;
+    //    * }
+    //    * ```
+    //    *
+    //    * Rush将调用此脚本，工作目录设置为monorepo根文件夹，
+    //    * 没有保证已运行 `rush install`。为确保警报的最新，Rush
+    //    * 可能会在不可预测的临时路径中获取和检出“common/config/rush-alerts”文件夹。
+    //    * 因此，你的脚本应避免从其文件夹外部导入依赖，
+    //    * 通常应保持尽可能简单、可靠和快速。对于更复杂的条件，
+    //    * 我们建议设计一些其他过程来准备一个数据文件或环境变量，
+    //    * 该变量可以由你的条件脚本便宜地检查。
+    //    */
+    //   // "conditionScript": "rush-alert-node-upgrade.js"
+    // }
+  ]
+}
+````
+
+## 另见
+
+- [rush init](../commands/rush_init.md)

websites/rushjs.io/sidebars.js

@@ -146,6 +146,7 @@ const sidebars = {
         'pages/configs/experiments_json',
         'pages/configs/pnpm-config_json',
         'pages/configs/rush_json',
+        'pages/configs/rush-alerts_json',
         'pages/configs/rush-plugin-manifest_json',
         'pages/configs/rush-plugins_json',
         'pages/configs/rush-project_json',