将项目添加到仓库

这将继续从“设置新仓库”开始的教程。（要查看基于这些步骤的完整示例，请查看 GitHub 上的 rush-example 仓库。）

步骤 4：添加您的第一个项目

我们建议不要一次性将所有项目都添加到 rush.json 中，而是建议一次添加并验证一个项目。请记住，您的项目形成了一个依赖关系图，因此从“叶子”项目（在仓库中不依赖于任何其他项目）开始，然后向后工作。如果您遇到任何错误，这种方法将使您更容易理解和调查它们。如果您单独提交每个添加的项目，这也将使您的 Git 历史记录对其他人更易于理解。

在本示例中，让我们从添加假想的 my-toolchain 项目开始，该项目是构建所有其他项目的必要条件。由于我们将遵循“类别文件夹”模型（在 rush.json 注释中描述），因此我们将此项目移至“tools”类别文件夹下。最终，我们计划将其他 NodeJS 工具包放在“tools”文件夹中

~/my-repo$ mkdir tools
~/my-repo$ cd tools
~/my-repo/tools$ cp -R ~/my-toolchain/ .
~/my-repo/tools$ cd my-toolchain

接下来，我们需要删除在单一仓库中集中协调的特定于项目的目录

删除本地 shrinkwrap 文件，因为它被 Rush 的公共 shrinkwrap 文件取代。
考虑删除项目的 .npmrc 文件，因为 Rush 操作始终使用 common/config/rush/.npmrc
考虑删除项目的 Git 配置文件，除非它们包含特定于该项目的规则

~/my-repo/tools/my-toolchain$ rm -f shrinkwrap.yaml npm-shrinkwrap.json package-lock.json yarn.lock
~/my-repo/tools/my-toolchain$ rm -f .npmrc          # (if it makes sense)
~/my-repo/tools/my-toolchain$ rm -f .gitattributes  # (if it makes sense)
~/my-repo/tools/my-toolchain$ rm -f .gitignore      # (if it makes sense)

有关“shrinkwrap 文件”的更多信息
根据您的包管理器，shrinkwrap 文件可能被称为 shrinkwrap.yaml、npm-shrinkwrap.json、package-lock.json 或 yarn.lock。（一些包管理器使用术语“锁定文件”，尽管它与文件锁定无关。在本文档中，我们将泛称为“shrinkwrap 文件”，因为我们不知道您将选择哪个包管理器。）
通常，包管理器会在每个项目文件夹中创建一个 shrinkwrap 文件，但在 Rush 仓库中，只有一个“公共”shrinkwrap 文件描述整个仓库。它将存储在 common/config/rush 文件夹中，应提交到 Git。将所有依赖关系信息合并到单个 shrinkwrap 文件中，对减少合并冲突、审查差异以及提高安装速度有很多好处。

将新项目文件提交到 Git

~/my-repo/tools/my-toolchain$ cd ../..
~/my-repo$ git add .
~/my-repo$ git commit -m "Adding my-toolchain"

步骤 5：运行您的第一个“rush update”

在复制完项目文件后，我们需要编辑 rush.json 并像这样在 projects 目录下添加一个条目

  "projects": [
    {
      "packageName": "my-toolchain",
      "projectFolder": "tools/my-toolchain"
    }
  ]

这告诉 Rush 应该管理此项目。

为什么 Rush 不能自动检测我的项目？
Rush 不会使用通配符自动发现项目。我们对这一设计决策有几个动机
深度优先扫描很昂贵，尤其是在工具需要重复收集列表时。
在缓存的 CI 计算机上，扫描可能会意外地拾取来自先前构建的遗留文件。
拥有所有项目及其重要元数据的集中目录非常有用。例如，这使得批准/策略功能更直观。

接下来，运行 rush update 来安装 my-toolchain 的依赖项。此命令可以在包含 rush.json 的仓库文件夹的任何子文件夹中运行

~/my-repo$ rush update
~/my-repo$ git add .
~/my-repo$ git commit -m "rush update"

由于这是仓库的第一个项目，您会注意到 rush update 创建了几个新文件

common/config/rush/shrinkwrap.yaml：公共 shrinkwrap 文件（这里假设使用 PNPM 包管理器）
common/scripts/install-run-rush.js：CI 作业使用它以可靠的方式引导 Rush 工具
common/scripts/install-run.js：CI 作业使用它以可靠的方式引导任意工具

步骤 6：验证新项目是否构建

为了构建您的项目，Rush 将在您的 package.json 文件的 "scripts" 部分中寻找一个 "build" 脚本。在我们来自 rush-example 的示例中，该项目使用一个简单的 shell 脚本 "rimraf ./lib/ && tsc" 进行构建

{
  "name": "my-toolchain",
  "version": "1.0.0",
  "description": "An example toolchain used to build projects in this repo",
  "license": "MIT",
  "bin": {
    "my-build": "bin/my-build.js"
  },
  "scripts": {
    "build": "rimraf ./lib/ && tsc"
  },
  "dependencies": {
    "colors": "^1.3.2"
  },
  "devDependencies": {
    "@types/node": "^10.9.4",
    "rimraf": "^2.6.2",
    "typescript": "^3.0.3"
  }
}

创建 "build" 脚本时，需要注意以下几点

Rush 通常会使用您的系统 PATH 环境变量来查找脚本命令。但是，如果您指定一个单字命令（如“heft”或“make”），Rush 将首先在 common\temp\node_modules\.bin 文件夹中查找该程序。
如果该进程返回一个非零退出状态，Rush 将假定出现错误，并将阻止下游构建。
如果该命令向 stderr 流写入任何内容，Rush 将将其解释为至少报告了一个错误或警告。这将中断构建。（这是设计使然——如果您允许人们合并报告“虚假警报”的 PR，很快您就会发现已经积累了太多警告，以至于没有人再阅读它们。）一些工具库（例如 Jest）在正常运行时会向 stderr 写入内容；您需要重定向它们的输出。
如果某些项目不需要由 rush build 处理，您仍然需要一个 build 条目。将该值设置为一个空字符串（""），Rush 将忽略它。

现在让我们尝试构建您的项目。在包含 rush.json 的文件夹下的任何位置，运行此命令（它将构建仓库中的所有项目）

rush build

Rush 提供了许多用于构建项目的命令行开关。有关详细信息，请参阅 rush build 和 rush rebuild。

虚假依赖错误
Rush 和 PNPM 使用符号链接来防止项目导入虚假依赖。如果您的 package.json 文件中未声明 NPM 依赖项，则如果您的项目尝试导入它，可能会发生运行时错误。这些虚假依赖错误是将现有项目迁移到 Rush 单一仓库中最常见的问题之一。通常，解决方法是只需将缺少的依赖项添加到您的 package.json 文件中。
rush scan 命令是一种快速检测这些问题的方法。

步骤 7：添加更多项目

您可以通过遵循步骤 4 中的相同操作来添加更多项目。在我们的示例中，我们将接下来添加 my-controls（因为它依赖于 my-toolchain），然后最后添加 my-application（因为它依赖于所有项目）。我们主动添加了几个其他类别文件夹（“libraries”和“apps”），因为我们预计在我们的场景中会有更多此类内容。填写后的 "projects" 部分如下所示

  "projects": [
    {
      "packageName": "my-app",
      "projectFolder": "apps/my-app"
    },

    {
      "packageName": "my-controls",
      "projectFolder": "libraries/my-controls",
      "reviewCategory": "production"
    },

    {
      "packageName": "my-toolchain",
      "projectFolder": "tools/my-toolchain",
      "reviewCategory": "tools"
    }
  ]

一旦您添加了所有项目，并且它们在没有错误的情况下构建，您可能会考虑启用其他可选功能。配置文件包含许多可以取消注释以开始使用的代码段。rush-example 仓库使用了一些这些代码段。

步骤 4：添加您的第一个项目​

步骤 5：运行您的第一个“rush update”​

步骤 6：验证新项目是否构建​

步骤 7：添加更多项目​

步骤 4：添加您的第一个项目

步骤 5：运行您的第一个“rush update”

步骤 6：验证新项目是否构建

步骤 7：添加更多项目