Release notes summary - What our users need to know

Release notes summary - What our users need to know

Cool command

This change adds a cool new feature. Here's how you use it:

my-cool-command

最终在 release notes 中会显示为 "Cool command" 标题下的段落。

### 链接与引用 issue

PR 描述中可使用 GitHub 的 linking keyword 自动关联 issue，例如：

- `Fixes #xxxx`
- `This PR should close #xxxx`

也可以顺带 mention 相关的 issue、PR 或 discussion。

## 本地检查：`toolkit check pr` 及其底层命令

CI 会自动检查代码格式并运行测试。在提交 PR 之前，可以在本地运行等价的检查。Nushell 仓库自带一套用 Nushell 脚本编写的开发工具链 [toolkit.nu](https://gitcode.com/GitHub_Trending/nu/nushell/blob/a854062f550a233ea8a3012d41634d07e3600f1d/toolkit.nu?utm_source=gitcode_repo_files)（模块入口为 [toolkit/mod.nu](https://gitcode.com/GitHub_Trending/nu/nushell/blob/a854062f550a233ea8a3012d41634d07e3600f1d/toolkit/mod.nu?utm_source=gitcode_repo_files)），其设计目的正如模块注释所述：为开发者在 PR 周期内提供统一接口，完成（1）格式化源码、（2）用 Clippy 发现常见缺陷、（3）确认所有测试通过。

```nushell
use toolkit.nu # 也可以通过 env_change hook 自动激活
toolkit check pr

从源码 toolkit/checks.nu 可以看到，check pr 实际按顺序执行四个阶段，任一阶段失败即生成带状态的阶段报告（fmt → clippy → test → test stdlib），并固定 locale 环境变量以避免本地化差异影响测试：

export def "check pr" [
    --fast # 使用 cargo-nextest 加速测试
    --features: list<string> # 指定要检查的 feature
] {
    # ...
    try { fmt --check --verbose } catch { return (report --fail-fmt) }
    try { clippy --features $features --verbose } catch { return (report --fail-clippy) }
    # ...
    try { test --workspace } catch { return (report --fail-test) }
    try { test stdlib } catch { return (report --fail-test-stdlib) }
    report --no-fail
}

各阶段也可以单独运行，toolkit 的每个子命令都有对应的底层 cargo 命令：

检查项	toolkit 命令	底层命令
格式检查	toolkit fmt --check	cargo fmt --all -- --check
应用格式	toolkit fmt	cargo fmt --all
Clippy	toolkit clippy	cargo clippy --workspace -- -D warnings -D clippy::unwrap_used
全量测试	toolkit test	cargo test --workspace
标准库测试	toolkit test stdlib	cargo run -- -c "use toolkit.nu; toolkit test stdlib"

CONTRIBUTING.md 给出的原始命令清单（在 cargo workspace 多 crate 结构下，可能需要比你熟悉的单 crate 项目传递更多 flag）：

• 构建并运行 Nushell：cargo run

• 运行 Clippy：

  cargo clippy --workspace -- -D warnings -D clippy::unwrap_used
  

  或 use toolkit.nu clippy 后执行 clippy。注意 toolkit/checks.nu 中实际执行的命令比文档中更严格：除 -D warnings -D clippy::unwrap_used 外还追加了 -D clippy::unchecked_time_subtraction，并且会排除 nu_plugin_* 单独处理（插件单独跑一轮 Clippy；测试代码中则不 deny unwrap）。源码注释还提醒：修改这些设置时须同步修改 CI 工作流配置；

• 运行全部测试：cargo test --workspace，或 use toolkit.nu test 后执行 test（--fast 时改用 cargo nextest run）；

• 运行某个命令的测试：

  cargo test --package nu-cli --test main -- commands::<command_name_here>
  

• 检查格式：cargo fmt --all -- --check；应用格式：cargo fmt --all；

• 安装 git hooks，在 commit/push 前自动检查格式并跑 Clippy：

  use toolkit.nu setup-git-hooks
  setup-git-hooks
  

  该 hook 目前不支持 Windows（对应实现见 toolkit/git-hooks.nu）。

如果本地检查全部通过而 CI 仍失败，可以向核心团队求助。

开发环境：构建、测试与调试

环境搭建

Nushell 需要较新的 Rust 工具链及若干系统依赖（以官方 Nu Book 的"从源码构建"章节为准）。安装好依赖后，构建方式与其他 Rust 项目一致：

git clone https://github.com/nushell/nushell
cd nushell
cargo build

仓库根目录的 rust-toolchain.toml 声明了所使用的 Rust 工具链版本。结合 devdocs/rust_style.md 的说明，Nushell 出于发行版打包考虑，通常落后最新稳定版 Rust 约两个版本，且禁止使用 nightly 特性。

测试的组织方式

CONTRIBUTING.md 建议：为改动补充测试，并主动考虑角落场景（corner cases）。仓库中测试分布在三处：

• 顶层 tests/ 目录（集成测试，含 repl/、parsing/、shell/ 等子模块）；
• 命令的 examples（每个命令自带的示例，会作为可执行测试运行）；
• 各 crate 自身的测试（如 crates/nu-protocol/tests/、crates/nu-std/tests/ 等）。

多数测试构建在 nu-test-support crate 之上（见 crates/nu-test-support/），其中提供简单的 run_test() 与 fail_test() 辅助函数；对于"在 REPL 模式下运行 Nushell"这类特殊场景，仓库提供了所谓的 "testbins" 辅助可执行文件（见 crates/testbins/）。标准库（nu-std）的测试则是 Nushell 脚本，位于 crates/nu-std/tests/，通过 toolkit test stdlib 驱动执行——对应实现即 toolkit/checks.nu 中 test stdlib 对 use crates/nu-std/testing.nu; testing run-tests --path crates/nu-std 的调用。

调试技巧

开发阶段开启 trace 日志级别查看详细日志：

cargo run --release -- --log-level trace

将 trace 日志重定向到文件，再查看：

cargo run --release -- --log-level trace --log-target file
open $"($nu.temp-dir)/nu-($nu.pid).log"