Zulip Terminal - Zulip 的官方终端客户端

近期更改 | 配置 | 快捷键 | 常见问题 | 开发 | 教程

关于

Zulip Terminal 是 Zulip 的官方终端客户端，提供 基于文本的用户界面 (TUI)。

具体目标包括：

• 提供与 Zulip Web 客户端广泛相似的用户体验， 最终支持其所有功能
• 使所有操作都可以通过键盘完成（参见 热键)
• 探索适合显示和输入 约束的替代用户界面设计
• 支持广泛的平台和终端模拟器
• 充分利用可用的行/列，从 80x24 向上扩展（参见 小终端说明)

通过我们的 教程 学习如何使用 Zulip Terminal。

功能状态

我们认为该客户端已经提供了相当稳定的、功能适中的 日常用户体验。

当前的开发重点在于改进日常使用中 更常用的方面——以减少用户为了特定功能而临时切换到 其他客户端的需求。

我们预计只能在长期内解决的当前限制包括对以下内容的支持：

• 拥有额外权限（所有者/管理员）的用户执行的所有操作
• 访问和更新所有设置
• 使用鼠标/指针完成所有操作
• 国际化的用户界面

有意为之的差异

终端客户端目前与 Zulip 网页客户端存在一些有意为之的差异：

• 额外的，偶尔不同的 快捷键 以更好地支持仅键盘导航；除了方向移动外， 还包括：
  • z - 放大/缩小，在频道与主题之间，或所有私信与特定对话之间
  • t - 切换左侧面板中频道主题的视图 （后来被网页客户端用于最近主题）
  • # - 筛选出提及你的消息（@ 已被使用）
  • f - 筛选出你已加星的消息（正在following）
• 当对话末尾可见时，不将额外消息标记为已读 (FAQ 条目)
• Emoji 和反应仅以文本形式渲染，以实现最大的终端/字体 兼容性
• 脚注链接 - 链接（URL）的脚注 - 使消息可读，同时 保留一个链接列表以供交叉引用
• 可在网页客户端中预览的内容，例如图片，也作为 脚注链接存储

功能查询？

对于缺失功能支持的查询，请查看 常见问题解答 (FAQs)， 我们开放的 Issues，或 在线与用户和开发者聊天 在 Zulip 社区服务器上！

安装

我们建议在专用的 python 虚拟环境中安装（见下文） 或使用自动化工具，例如 pipx

• 稳定版本 - 这些版本以软件包 zulip-term 的形式在 PyPI 上提供

  要安装，请运行类似以下命令： pip3 install zulip-term

• 最新版本（git） - 最新的开发版本可以从 git 仓库的 main 分支安装

  要安装，请运行类似以下命令： pip3 install git+https://github.com/zulip/zulip-terminal.git@main

我们还提供了一些示例 Dockerfile，用于构建 docker 镜像，位于 docker/。

安装到隔离的 Python 虚拟环境

由于运行需要 python 3.6+，以下操作在大多数 系统上应该可以正常工作：

1. python3 -m venv zt_venv （在当前目录中创建一个名为 zt_venv 的虚拟环境）
2. source zt_venv/bin/activate （激活虚拟环境；这假设使用的是类 bash shell）
3. 运行上述任一安装命令。

如果你打开另一个终端窗口（或注销/重启你的计算机）， 在运行 zulip-term 之前，你需要再次运行上述列表中的 步骤 2，因为该步骤会激活该虚拟环境。 你可以在 Python 3 库 venv 文档 中阅读更多关于虚拟环境的信息。

保持安装为最新状态

请注意，没有自动更新系统，因此请跟踪与你安装版本相关的更新 位置：

稳定版本

在升级之前，我们建议你查看 近期版本中的更改 以便你了解版本之间的重要更改。

• 这些现在会在 Zulip Community 服务器（https://chat.zulip.org）的 #announce>terminal releases 主题中宣布，该主题无需账户即可查看。

如果您希望在更新发布时收到电子邮件通知，欢迎 在此服务器上注册一个账户，这将使您能够启用 #announce 频道 (帮助文章, chat.zulip.org 上的通知设置)的电子邮件通知。

• 您还可以在项目页面上自定义 GitHub Watch 设置，以包含发布版本。

• PyPI 提供 RSS 发布源，并且 其他各种服务也跟踪此信息。

最新（git）版本

从 main git 分支安装的版本也不会自动更新 ——“latest”指的是安装时的状态。

这也适用于其他源代码或开发安装 （例如 https://aur.archlinux.org/packages/python-zulip-term-git/）。

因此，请使用上述命令升级您的软件包，或使用与 您的软件包系统相关的命令（例如 Arch）。

虽然 main 分支旨在保持稳定，但在两个 任意“latest”版本之间升级时，请注意变更未进行摘要， 尽管我们的提交日志应该非常易读。

首次运行

首次运行 zulip-term 时，它会查找 zuliprc 文件，默认位于 您的主目录中，该文件包含登录 Zulip 服务器的详细信息。

如果未找到此文件，您有两个选择：

1. zulip-term 会提示您输入服务器、电子邮件和密码，并在该位置 为您创建一个 zuliprc 文件

注意： 如果您使用 Google、Github 或其他外部身份验证来 访问您的 Zulip 组织，那么您可能尚未设置密码，并且 目前需要创建一个密码才能使用 zulip-terminal。

• 如果您的组织位于 Zulip 云上，您可以访问 https://zulip.com/accounts/go?next=/accounts/password/reset 为您的账户 创建新密码。
• 对于自托管服务器，请前往您的 <Zulip server URL>/accounts/password/reset/ 等效页面来为您的 账户创建新密码（例如：https://chat.zulip.org/accounts/password/reset/）。

2. 每次运行 zulip-term 时，您可以使用 -c 或 --config-file 选项指定替代 zuliprc 文件的路径，例如 $ zulip-term -c /path/to/zuliprc

   与您在特定 Zulip 服务器上的账户相对应的 .zuliprc 文件 可以通过连接到该服务器的 Web 或桌面应用程序下载。 在较新的版本中，您可以在 账户与隐私 部分的 个人设置 中找到它，位于 API 密钥 下的“显示/更改您的 API 密钥”。

   如果这是您唯一的 Zulip 账户，您可能希望将此 文件移动并重命名到上述默认文件位置，或者将其重命名为更 易记的名称，以便传递给 ---config-file 选项。 此 .zuliprc 文件赋予您作为该用户所拥有的所有权限。

   类似的 .zuliprc files 可以从 机器人 部分下载，用于您设置的任何 机器人，但权限相应受限。

注意： 如果你的服务器使用自签名证书或不安全的 连接，你需要手动在 zuliprc 文件中添加额外的选项 - 请参阅 Zulip python module 的文档。

我们建议在你第一次尝试 Zulip Terminal 时，使用 -e 或 --explore 选项（在 探索模式下）运行 zulip-term，在这种模式下我们 故意不将消息标记为已读。请尝试跟随我们的 教程 来熟悉操作。

配置

zuliprc 文件包含两个部分：

• 一个 [api] 部分，包含连接到你的 Zulip 服务器所需的信息
• 一个 [zterm] 部分，包含特定于 zulip-term 的配置

在某些情况下，仅包含第一个部分的文件可以由 zulip-term 自动生成，或者你可以从服务器上的你的账户下载一个（见 上文）。当你希望自定义 zulip-term 的行为时，可以分阶段添加和调整第二个部分的某些内容。

下面的示例，带有虚拟的 [api] 部分内容，代表了一个可用的 配置文件，其中所有默认兼容的 [zterm] 值均未注释 并附有相关说明：

[api]
email=example@example.com
key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
site=https://example.zulipchat.com

[zterm]
## Theme: available themes can be found by running `zulip-term --list-themes`, or in docs/FAQ.md
theme=zt_dark

## Autohide: set to 'autohide' to hide the left & right panels except when they're focused
autohide=no_autohide

## Exit Confirmation: set to 'disabled' to exit directly with no warning popup first
exit_confirmation=enabled

## Footlinks: set to 'disabled' to hide footlinks; 'enabled' will show the first 3 per message
## For more flexibility, comment-out this value, and un-comment maximum-footlinks below
footlinks=enabled
## Maximum-footlinks: set to any value 0 or greater, to limit footlinks shown per message
# maximum-footlinks=3

## Notify: set to 'enabled' to display notifications (see elsewhere for configuration notes)
notify=disabled

## Color-depth: set to one of 1 (for monochrome), 16, 256, or 24bit
color-depth=256

## Transparency: set to 'enabled' to allow background transparency
## This is highly dependent on a suitable terminal emulator, and support in the selected theme
## Terminal emulators without this feature may show an arbitrary solid background color
transparency=disabled

## Editor: set external editor command, to edit message content
## If not set, this falls back to the $ZULIP_EDITOR_COMMAND then $EDITOR environment variables
# editor: nano

注意： 这些配置设置中的大多数可以在 启动 zulip-term 时通过命令行指定；zulip-term -h 或 zulip-term --help 将提供完整的选项列表。

通知

请注意，目前 WSL 不支持通知；请参阅 #767。

Linux

以下命令在基于 Debian 的系统上安装 notify-send，其他 Linux 系统也可以找到类似的命令。

sudo apt-get install libnotify-bin

OSX

在 OS X 上启用通知无需额外软件包。 但若要使用通知声音，请设置以下变量（基于您的 shell 类型）。 声音值（此处为 Ping）可以是 .aiff 中位于 /System/Library/Sounds 或 ~/Library/Sounds 的任意一个文件。

Bash

echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.bash_profile
source ~/.bash_profile

ZSH

echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.zshenv
source ~/.zshenv

复制到剪贴板

Zulip Terminal 允许用户通过 Python 模块将特定文本复制到剪贴板，Pyperclip. 该模块利用了各种系统软件包，这些软件包可能随 操作系统提供，也可能不提供。 “复制到剪贴板”功能目前仅可用于复制 Stream 邮箱，来自 Stream 信息弹窗.

Linux

在 Linux 上，该模块利用了 xclip、xsel 或 wl-clipboard 实用工具， 其中 xclip 和 xsel 用于 X11 环境（两者中，推荐 使用 xclip 而非 xsel），而 wl-clipboard 用于 Wayland 环境。 （如果您不确定自己使用的是哪种系统，请检查 $WAYLAND_DISPLAY 环境变量；在 Wayland 中，该变量通常会被设置为类似 wayland-0 的值，而在 X11 中，该变量将未设置。）

如果您的系统未安装这些命令中的任何一个，请使用适合您系统的 包管理器安装上述实用工具中的一个，例如：

sudo apt-get install xclip

或

sudo apt-get install wl-clipboard

OSX 和 WSL

启用复制到剪贴板功能无需额外软件包。

与其他用户和开发者聊天！

虽然 Zulip Terminal 旨在与任何 Zulip 服务器配合使用，但主要贡献者都在 https://chat.zulip.org 上的 Zulip Community 服务器上，大部分对话都在 #zulip-terminal 频道中进行。

欢迎通过上述链接查看该频道中的对话，或者注册一个账户与我们聊天——无论你是用户还是开发者！

我们致力于保持 Zulip 社区友好、包容且富有成效，因此如果你参与讨论，请尊重我们的 社区规范。

与 #zulip-terminal 频道更相关的注意事项

这些是上述链接中 社区规范 的一个子集，与 Zulip Terminal 的用户更为相关：他们更可能处于文本 环境中，受限于字符行/列数，并且存在于这个较小的 频道中。

• 优先使用 代码块中的文本，而不是截图

  Zulip Terminal 支持下载图片，但不能保证 用户能够查看它们。

  尝试 Meta+m 以查看示例内容格式，包括代码块

• 优先使用 静默提及 而非普通提及——或者完全避免提及

  借助 Zulip 的主题，预期接收者通常已经很清楚。 经验丰富的成员会在时间允许时出现——在他们返回时 回复消息——其他人也可能在此之前提供帮助。

  （将 普通提及 留给那些你不期望经常在线的人）

尝试使用 Ctrl+f/b 在消息内容中循环切换自动补全，在输入 @_ 以指定静默提及之后

• 优先将 引用和回复 文本修剪为较长消息中仅相关的部分 - 或完全避免引用

  Zulip 的主题通常能清楚地表明你正在回复哪条消息。长消息在有限的行数和列数下可能更难阅读， 但如果引用包含额外内容的整条长消息，这种情况会变得更糟。

  尝试使用 > 来引用选定的消息，在撰写消息时像往常一样删除文本

• 优先使用 快速表情回应 来表示同意，而不是简单的短消息

  表情回应占用更少的空间，包括在 Zulip Terminal 中，特别是 当多个用户希望以相同的情感回应时。

  尝试使用 + 来切换消息的大拇指向上（+1），或使用 : 来搜索其他回应

贡献者指南

Zulip Terminal 是由出色的 Zulip 社区构建的。

要参与其中并为代码做出贡献，请随意处理任何 问题 或在 #zulip-terminal 上提出你的想法。

关于提交结构和风格，请查看下面的 提交风格 部分。

如果你是 git 的新手（或者不是！），你可能会从 Zulip git 指南 中受益。 在贡献时，重要的是要注意我们使用 基于 rebase 的 工作流。

一个简单的 教程](https://github.com/zulip/zulip-terminal/blob/main/docs/developer-feature-tutorial.md) 可用于实现 typing 指标。 按照它来了解如何为 zulip-terminal 实现新功能。

当然，你可以浏览 GitHub 上的源代码以及你 下载的源码树，并查看 源文件概览 以了解文件当前的组织方式。

Urwid

Zulip Terminal 使用 urwid 在 终端中渲染 UI 组件。 Urwid 是一个出色的库，你可以仅使用 python 就通过它渲染出不错的终端 UI。 Urwid 的教程 是 新贡献者开始学习的好地方。

获取 Zulip Terminal 代码并将其连接到上游

首先，在 GitHub 上 fork zulip/zulip-terminal 仓库 （查看方法） 然后在本地克隆你 fork 的仓库，将 YOUR_USERNAME 替换为 你的 GitHub 用户名：

$ git clone --config pull.rebase git@github.com:YOUR_USERNAME/zulip-terminal.git

这将在当前目录中为仓库创建一个新目录， 因此使用 cd zulip-terminal 进入仓库目录，并配置和 获取你的 Zulip Terminal 克隆分支的上游远程仓库：

$ git remote add -f upstream https://github.com/zulip/zulip-terminal.git

有关用于克隆和设置上游的命令的详细说明， 请参阅 获取 Zulip 代码 Zulip 的 Git 指南中的第 1 步。

搭建开发环境

有多种选项可供选择；我们正在探索每种选项的优势，并 希望获得关于您使用或认为效果最佳的选项的反馈。

请注意，每种情况下使用的工具通常相同，但调用方式不同。

以下命令应在由类似上一节流程创建的仓库目录中运行。

Pipenv

1. Install pipenv (see the recommended installation notes; pipenv can be installed in a virtual environment, if you wish)

$ pip3 install --user pipenv

2. Initialize the pipenv virtual environment for zulip-term (using the default python 3; use eg. --python 3.6 to be more specific)

$ pipenv --three

3. 安装 zulip-term，包含开发依赖

$ pipenv install --dev
$ pipenv run pip3 install -e '.[dev]'

4. 连接 gitlint commit-message 钩子

$ pipenv run gitlint install-hook

Pip

1. 手动创建并激活虚拟环境；任何方法均可， 例如上述简单安装中所使用的方法

2. python3 -m venv zt_venv（在当前目录创建一个名为 zt_venv 的 venv） 2. source zt_venv/bin/activate（激活 venv；此操作假设使用类 bash 的 shell）

3. 安装 zulip-term，包含开发依赖项

$ pip3 install -e '.[dev]'

3. 连接 gitlint commit-message 钩子

$ gitlint install-hook

make/pip

这是最新且最简单的方法，如果你已安装 make：

1. make（在当前目录的 zt_venv 中设置已安装的虚拟环境）
2. source zt_venv/bin/activate（激活 venv；此操作假设使用类 bash 的 shell）
3. gitlint install-hook（连接 gitlint commit-message hook）

开发任务

一旦你搭建好了开发环境，根据你所处的环境类型，你可能会发现以下内容有用：

任务	Make & Pip	Pipenv
正常运行	zulip-term	pipenv run zulip-term
以调试模式运行	zulip-term -d	pipenv run zulip-term -d
以性能分析模式运行	zulip-term --profile	pipenv run zulip-term --profile
运行所有 linter	./tools/lint-all	pipenv run ./tools/lint-all
运行所有测试	pytest	pipenv run pytest
构建测试覆盖率报告	pytest --cov-report html:cov_html --cov=./	pipenv run pytest --cov-report html:cov_html --cov=./

如果使用 make 配合 pip，运行 make 将确保开发环境 与指定的依赖项保持最新，这在从 git 获取并变基之后非常有用。

编辑源代码

选择你最喜欢的文本编辑器或开发环境！

源文件包含一个 .editorconfig 文件，它使许多编辑器能够 自动配置自身，以生成满足项目最低 要求的文件。有关编辑器支持，请参阅 https://editorconfig.org； 请注意，如果您希望使用此功能，某些编辑器可能需要插件。

运行 linter 和自动化测试

当您提交拉取请求（PR）或向现有 拉取请求推送更改时，linter 和自动化测试（pytest）会在 CI（GitHub Actions）中自动运行。

然而，在您的计算机上运行这些检查可以通过 避免反复将代码推送到 GitHub 来加快开发速度。 实现此目的的命令列在上方的开发任务表中 （也可以通过 tools/ 中的脚本单独运行各个 linter）。

此外，如果使用基于 make 的系统：

• make lint 和 make test 分别运行每组任务中的所有任务
• make check 运行所有检查，这在推送 PR（或更新）之前很有用
• tools/check-branch 将对您分支中的每个提交运行 make check

注意：在 所有 linter 和测试通过之前，包括按提交计，拉取请求被合并的可能性极低。

我的分支/PR 上的 linter 和测试未通过 - 我该怎么办？

纠正某些 linting 错误需要手动干预，例如来自 mypy 的类型检查。

有关测试的技巧，请参阅下方关于 pytest 的章节。

然而，其他 linting 错误可以自动修复，详见下文 - 这可以节省大量手动调整代码以通过 linter 的时间！

如果你难以理解为什么 linter 或 pytest 会失败， 请将你的代码推送到分支/PR，我们可以 在 PR 或 chat.zulip.org 上讨论这些问题。

自动更新热键 & 文件 docstring，以及相关文档

如果你更新了这些内容，请注意你无需手动更新两处 的文本以通过 linting。

事实来源在源代码中，因此只需更新 python 文件并 运行相关工具。目前我们有：

• tools/lint-hotkeys --fix 用于从 config/keys.py 重新生成 docs/hotkeys.md
• tools/lint-docstring --fix 用于从文件 docstring 重新生成 docs/developer-file-overview.md

（这些工具也用于 linting 过程，以确保这些文件 保持同步）

自动格式化代码

该项目分别使用 black 和 isort 进行代码样式和 import 排序。

这些工具可以作为 linter 在本地运行，但也可以自动 为你格式化代码。

如果你使用的是基于 make 的配置，运行 make fix 将运行两者（以及 其他几个工具）并重新格式化你当前代码的状态 - 因此你最好 先提交，以防万一，然后如果你对这些更改感到满意，就 --amend 该提交。

你也可以在文件或目录上单独使用这些工具，例如 black zulipterminal 或 isort tests/model/test_model.py

组织 Commits - 加速审查、合并 & 开发

当你在本地工作，调查需要进行的更改时，通常会创建一系列小的提交来保存你的进度。 这通常包括修复之前提交中的 linting 或测试问题的提交。 这些是开发风格的提交 - 几乎每个人在某种程度上都可能以这种风格编写提交。

开发风格的提交目前可以很好地为你保存更改。 然而，当分享你的代码时，提交信息是一个很好的地方，用于向他人传达你正在更改什么以及为什么。整理结构 也可以让读者更容易、更快地理解更改，并且表明你尊重他们的时间。一个例子是，非常大的单个提交 可能需要大量时间来审查，而将其拆分则不然。另一个是如果你在提交中修复了测试/linting：这个修复针对哪个提交（或哪些提交！），如果 它在同一个分支/PR 中，为什么不直接修复原始提交呢？

因此，在创建 Pull Request (PR) 时，请考虑你的代码 如果更容易阅读、理解和审查，则更有可能被更快地合并 - 而其中很大一部分在于你如何将更改结构化为 提交，并在提交信息中描述这些更改。

为了保持高效并让你的 PR 更容易被审查和更新，我们 遵循在 Zulip 及其他地方采用的方法，旨在让 PR 由一系列最小且连贯的 提交组成：

• 最小： 查看每个提交。它是否对许多文件进行了不同类型的更改？你是否将提交标题当作更改列表？ 考虑 如何将一个大更改分解为一系列较小的更改，这些更改你可以轻松单独描述，并且可以依次流动。
• 连贯： 每个提交都应单独通过所有 linting 和现有的自动化 测试，如果你添加了新行为，则添加或扩展测试以覆盖它。

请注意，遵循这些原则可以带来其他好处，无论是在审查 PR 之前、 期间还是之后，包括：

• 最小提交始终可以在稍后压缩（合并）在一起 - 拆分提交更具挑战性！
• 连贯提交意味着在提交之间和之后不应有任何损坏
  • 如果你分支中的新提交破坏了 linting/测试，很可能是该提交出了问题！
  • 这提高了 git bisect 在你的分支或 main 上的实用性
• 这些提交在分支中更容易重新排序
  • 分支开头的提交（或可以移动到的位置），可以早期合并以简化分支
• 当阅读由这些提交组成的 git log 时，理解做了哪些更改以及为什么更容易

我们现在在持续集成（CI）作业中强制执行 PR 中提交 coherent（连贯）特性的一个有限方面，即 Ensure isolated PR commits（确保 PR 提交相互隔离），其本质是在你分支的每个提交上运行 make check。你可以在推送到 GitHub 之前使用 tools/check-branch 在本地复现此操作。

虽然小型或概念验证（proof-of-concept）PR 最初可以按原样推送，但它们很可能仅基于整体变更进行审查。通常，如果单个提交看起来具有开发风格，审查者可能会给出较不具体的反馈，并且在合并之前肯定会要求提交最小化的连贯提交。

重构命令 - 大多数重构依赖于 交互式变基（interactive rebasing）（例如 git rebase -i upstream/main），但请考虑在线搜索特定操作，以及在 chat.zulip.org 的 #git help 或 #learning 频道中搜索或提问。

自我审查 - 另一种有用的方法是在本地（参见 Zulip 建议） 以及推送到 GitHub 之后审查你自己的提交。这允许你检查并修复任何看起来不合适的地方，这些内容很可能在审查中被指出，有助于让你的提交看起来更精致，同时也再次表明你尊重审查者的时间。

提交信息风格

我们旨在遵循标准的提交风格，以保持 git log 的一致性和易读性。

就像处理代码一样，我们建议你参考 git log 中的最近提交，以了解我们当前正在使用的风格示例。

我们的提交信息整体风格大致遵循 Zulip 提交信息 中给出的一般性指南， 因此我们建议先阅读该指南。

我们的提交标题（摘要）与 Zulip 的一般风格略有不同，每个标题：

• 以一个或多个领域开头 - 使用小写，后跟冒号和空格
  • 通常每个提交至少包含每个被修改文件的一个领域 - 不带扩展名，用 / 分隔
  • 通常不要在此列表中包含测试文件（而是在提交文本中使用 Tests updated 或 Tests added）
  • 其他常见领域包括诸如 refactor:、bugfix: 和 requirements: 的类型（见下文）
• 以一个简洁的描述结尾，以大写字母开头，以句号结尾
• 整体最大长度为 72（适配 github 网页界面，无需缩写）

一些提交标题示例：（实际中最好更具描述性！）

• file3/file1/file2: Improve behavior of something.
  • 一个通用的提交，更新文件 file1.txt、file2.py 和 file3.md
• refactor: file1/file2: Extract some common function.
  • 一个纯重构，不改变功能行为，涉及 file1.py 和 file2.py
• bugfix: file1: Avoid some noticeable bug.
  • 一个小提交，修复 file1.py 中的一个 bug
• tests: file1: Improve test for something.
  • 仅为 file1 改进测试，可能位于 test_file1.py
• requirements: Upgrade some-dependency from ==9.2 to ==9.3.
  • 将依赖项从版本 ==9.2 升级到版本 ==9.3，位于中央依赖文件中（不是某些 requirements.* 文件）

为了帮助满足其中一些规则，你可以使用 GitLint，如 下一节所述。

然而，请手动对照这些样式规则检查你的提交，因为 GitLint 无法检查所有内容——包括语言或语法！

GitLint

gitlint 工具默认安装在开发环境中，并且 可以帮助确保你的提交符合预期标准。

该工具可以手动检查特定提交，例如 gitlint 用于最新 提交，或 gitlint --commits main.. 用于从 main 开始的提交。 然而，我们强烈建议运行 gitlint install-hook 来安装 gitlint 提交信息钩子 （或在 pipenv 环境中使用 pipenv run gitlint install-hook）。

如果钩子已按上述描述安装，那么在完成 提交文本后，它将由 gitlint 根据我们设置的样式进行检查， 如果发现任何问题，会提供建议。 如果 gitlint 发现任何问题，它会询问你是否希望按原样提交该信息 （y 表示“是”），停止提交流程（n 表示“否”），或编辑提交 信息（e 表示“编辑”）。

虽然内容仍然取决于你的写作技巧，但这确保了不同 作者之间提交之间更一致的格式结构。

使用测试（pytest）的技巧

zulip-terminal 的测试是使用 pytest 编写的。 你可以阅读 /tests 文件夹中的测试来学习如何为 新的类/函数编写测试。 如果你是 pytest 的新手，强烈建议阅读其文档。

我们目前拥有数千个测试，在运行时会被检查 pytest。 虽然这取决于你的系统性能，但通常运行时间应 少于一分钟。 然而，在调试过程中，你可能仍希望限制测试的范围， 以提高周转时间：

• 如果大量测试以非常冗长的方式失败，你可以尝试 -x 选项（例如 pytest -x）以在第一次失败后停止测试；由于 测试参数化和测试夹具，许多明显的错误/失败可以 通过一次修复来解决！（例如尝试 pytest --maxfail 3 以获得此功能的 较宽松版本）

• 为了避免每次运行所有成功的测试以及失败的测试， 你可以使用 --lf（例如 pytest --lf）运行，它是 --last-failed 的缩写（类似有用的选项可能是 --failed-first 和 --new-first，它们可能 与 -x 配合良好）

• 从 pytest 3.10 开始，有 --sw（--stepwise），它通过已知的 失败以与 --lf 和 -x 相同的方式工作，并且可以 与 --stepwise-skip 结合使用，以控制当前关注的测试

• 如果你知道失败测试的名称和/或特定 位置，你可以将测试限制到特定位置（例如 pytest tests/model) or use a selected keyword (eg. pytest -k __handle）

当只有部分测试在运行时，使用 -v 选项（--verbose）变得更加实用和有用； 它不会为每个测试结果显示 .（或 F、E、x 等）， 而是显示正在运行的每个测试的名称（含参数）（例如 pytest -v -k __handle）。 此选项还会在测试中显示更多详细信息，并且可以多次指定 （例如 pytest -vv）。

如需有关 pytest 选项的更多帮助，请参阅 pytest -h，或查看 完整的 pytest 文档。

调试技巧

使用 print 输出

如果在运行时使用 -d 或 --debug 启用调试，zulip-terminal 的 stdout（标准输出） 将被重定向到 ./debug.log。

这意味着，如果你想检查某个变量的值，或者 指示代码执行到了某个特定点，你可以简单地使用 print()， 例如

print(f"Just about to do something with {variable}")

当使用调试选项运行时，该字符串将被打印到 ./debug.log。

在使用类似 bash 的终端中，你可以在 另一个终端中运行类似 tail -f debug.log 的命令， 以实时查看来自 print 的输出。

使用 pudb 和 telnet 进行交互式调试

如果你想调试正在运行的 zulip-terminal，或者调试其处于特定 状态时的情况，你可以在 想要调试的代码部分插入

from pudb.remote import set_trace
set_trace()

这将为你启动一个 telnet 连接。你可以在 ./debug.log 中找到 telnet 连接的 IP 地址和端口。然后在 另一个终端中运行

$ telnet 127.0.0.1 6899

其中 127.0.0.1 是 IP 地址，6899 是你在 ./debug.log 中找到的端口。

在 Zulip Terminal 中进行本地更改后没有效果！

这通常意味着你同时安装了 zulip-terminal 的普通版本和开发版本。

要确保你运行的是开发版本：

• 如果使用 pipenv，请从克隆/下载的 zulip-terminal 目录中调用 pipenv run zulip-term；

• 如果使用 pip (pip3)，请确保你已激活了正确的虚拟 环境 (venv)；根据你的 shell 配置，venv 的名称可能 会显示在命令提示符中。 请注意，在 pip3 命令中不包含 -e 也会导致此 问题。