Back to Details

upgrading-emdash

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Upgrading EmDash

升级 EmDash

Use 
upgrade-emdash
to resolve the selected npm release tag, update every direct EmDash package, refresh the EmDash skills, and create the project-specific work order. The updater does not edit application code, apply database migrations, or deploy.
使用 
upgrade-emdash
解析选定的 npm release tag，更新所有直接依赖的 EmDash package，刷新 EmDash skills，并创建项目专属的 work order。更新器不会修改应用代码、执行数据库迁移或进行部署。

Prepare the work order

准备 work order

Run from the project root:
sh
npx upgrade-emdash@latest --dry-run
npx upgrade-emdash@latest
Use 
--to <tag>
for another npm dist-tag such as 
next
or 
beta
. 
--to
does not accept a version. Use 
--yes
to accept the updater prompt in a non-interactive environment, 
--json
for a machine-readable dry-run, and 
--cwd <path>
when the project root is elsewhere.
The updater writes 
.emdash/UPGRADE.md
. Read that file after the command finishes. It contains the complete authored changelog entries crossed by the direct packages in this project, with generated dependency-bump entries removed, plus the exact core migration delta found after installation.
在项目根目录运行：
sh
npx upgrade-emdash@latest --dry-run
npx upgrade-emdash@latest
如需使用其他 npm dist-tag（例如 
next
或 
beta
），请使用 
--to <tag>
。
--to
不接受具体版本。在非交互式环境中，可使用 
--yes
接受更新器的提示；使用 
--json
获取机器可读的 dry-run 结果；如果项目根目录位于其他位置，则使用 
--cwd <path>
。
更新器会写入 
.emdash/UPGRADE.md
。命令完成后，请读取该文件。其中包含与本项目直接依赖的 packages 相交的完整人工编写 changelog 条目，已移除自动生成的依赖升级条目，并包含安装后发现的确切 core migration 差异。

Complete the upgrade

完成升级

  1. Inspect the existing project and its uncommitted changes. Preserve unrelated work.
  2. Assess every release entry in 
    .emdash/UPGRADE.md
    against the project. Apply required source and configuration changes. Do not adopt a new feature when the project does not use the affected surface.
  3. Run the repository's relevant format, tests, typecheck, and build commands.
  4. Run the migration status command from the work order and report the target database and pending migrations.
  5. When the work order lists added core migrations, the status command reports an earlier pending migration, or a release entry requires a data-changing project action, follow the work order's backup procedure before starting or deploying the upgraded application.
  6. Ask before applying a migration to a database, deploying, or making any other remote change unless the user explicitly included that action in the request.
  7. After authorized migration and deployment work, run the migration check and verify the affected site paths.
Treat core migrations as forward-only. A package update with no added or pending migrations does not require an upgrade-specific recovery point. Before an authorized database-changing step, require a restorable database backup created with Backups and recovery, a separate media backup, the relevant encryption keys, and the same build artifact for migration and deployment. A JSON backup is not a recovery point. Roll back by restoring the matching database and application artifact together, not by running migration 
down()
functions or deleting migration records.
  1. 检查现有项目及其未提交的更改。保留无关工作。
  2. 根据项目逐一评估 
    .emdash/UPGRADE.md
    中的每个发布条目。应用必要的源代码和配置更改。如果项目未使用受影响的功能范围，则不要采用新功能。
  3. 运行仓库中相关的 format、tests、typecheck 和 build 命令。
  4. 运行 work order 中指定的迁移状态命令，并报告目标数据库和待执行的迁移。
  5. 如果 work order 列出了新增的 core migrations、状态命令显示存在更早的待执行迁移，或者某个发布条目要求执行会更改数据的项目操作，请先按照 work order 中的备份流程操作，然后再启动或部署升级后的应用。
  6. 除非用户明确要求，否则在应用数据库迁移、进行部署或实施任何其他远程更改前，必须先征求用户同意。
  7. 完成获得授权的迁移和部署工作后，运行迁移检查并验证受影响的站点路径。
将 core migrations 视为仅向前执行。如果 package 更新未新增迁移且没有待执行迁移，则无需为此次升级单独创建恢复点。在执行获得授权的数据库更改步骤之前，必须具备通过备份与恢复创建且可还原的数据库备份、单独的媒体备份、相关加密密钥，以及用于迁移和部署的同一 build artifact。JSON 备份不能作为恢复点。回滚时，应同时还原匹配的数据库和应用 artifact，而不是运行 migration 
down()
函数或删除迁移记录。