vants.org

Appearance

Wireshark Wiki 中文翻译整理专题首页原始页面

开发/提交补丁 ​

本页整理 Wireshark Wiki 中关于提交补丁的历史说明：从 GitLab fork、分支、提交、merge request，到审查、修正、冲突处理、回移植和从 Gerrit 迁移的注意事项。

项目说明
用途帮助贡献者理解原 Wiki 记录的 GitLab 补丁提交流程。
适用场景准备提交 Wireshark 补丁、更新已有 merge request、测试他人的 merge request、处理发布分支回移植。
易混点本页导入自 2020 年，原文也说明这些说明正从 Gerrit 时代更新到 GitLab。实际贡献时应以当前 Wireshark Developer's Guide 和 GitLab 页面为准。

历史状态 ​

Wireshark 已于 2020 年 8 月 23 日从 Gerrit 迁移到 GitLab。原文提示：如果在 Gerrit 中还有未完成更改，应阅读“从 Gerrit 迁移”部分。有关贡献代码的完整说明，应参阅《开发者指南》中的贡献部分。

典型 GitLab 工作流 ​

阶段动作原文要点
准备账户登录 GitLab，添加 SSH key。可注册 GitLab，也可使用 GitHub、Google、Bitbucket 等账户登录。
创建个人副本在 https://gitlab.com/wireshark/wireshark/ 点击 Fork。生成个人 Wireshark 仓库副本。
克隆与 remote使用 upstream 指向官方仓库，downstream 指向个人仓库。原文示例采用 upstream/downstream 命名，但 remote 名称可自定。
初始化开发环境运行 tools/setup-dev.sh。原文指出这是设置开发环境和 git hooks 的最简单方式。
新建分支从 upstream/master 创建与更改相关的分支名。分支名可与 bug 编号或 dissector 名称相关。
修改与测试修改代码并测试。补丁提交前应确认更改正常工作。
提交使用 git add、git commit 或 git commit -a。新文件仍需显式 git add。
推送将当前分支推送到个人仓库。原文使用 git push downstream HEAD。
创建 MR到 GitLab 创建 merge request。保持允许维护者向源分支提交，以便 rebase 或调整。
审查与 CI在 MR 页面查看讨论、测试和状态。创建 MR 后会运行一系列测试。

命令速查 ​

以下是原文工作流的精简版，USERNAME 和 BRANCH_NAME 需要替换为你的 GitLab 用户名和分支名。

text
git clone -o upstream git@gitlab.com:wireshark/wireshark.git
cd wireshark
git remote add downstream git@gitlab.com:USERNAME/wireshark.git
tools/setup-dev.sh

git checkout -b BRANCH_NAME upstream/master
# 修改并测试
git add FILE1 FILE2
git commit
git push downstream HEAD

更新同一个 merge request 时，原文强调不要改分支名，因为 GitLab 用分支名关联已有 merge request。

text
git checkout BRANCH_NAME
# 修改并测试
git commit -a --amend
git push downstream +HEAD

Git hooks ​

选项用途注意
tools/setup-dev.sh设置开发环境，包括 git hooks。原文推荐的最简单方式。
Wireshark 自定义 pre-commit hook执行通用检查，以及 Wireshark 特定 API 和格式检查。可能误报；可从 tools 目录复制 pre-commit 到 .git/hooks/。
Git 示例 pre-commit hook检测混合制表符和空格等空白字符问题。可复制或重命名 .git/hooks/pre-commit.sample。
git commit --no-verify跳过 hooks。仅在你确认更改有效且 hook 阻止提交时使用。

提交消息 ​

要素原文要求
第一行极简短描述，少于 60 个字符。
协议前缀如果只针对单个协议，可用协议缩写加冒号开头。
草稿状态未完成更改可在第一行前加 Draft:。
空行第一行后插入空行。
详细描述后续行说明更改细节，按需分段，每行限制为 80 个字符。
issue 引用可用 #1234 引用 issue；Closes #1234 在合并时关闭对应 issue。
示例捕获如果为 dissector 贡献非平凡修复，原文建议打开 issue 并附示例捕获文件。
AI 声明原文希望声明是否使用 AI，例如 AI-Assisted: no 或 AI-Assisted: yes [tool(s)]。

示例按原文含义重排为可读格式：

text
MIPv6: Fix dissection of Service Selection Identifier

APN field is not encoded as a dotted string so the first character is not a
length. Closes #10323.

AI-Assisted: no

修正已有更改 ​

场景做法
更新 MR 内容检出现有分支，继续修改和测试。
替换已有提交使用 git commit --amend，再强制推送到同一分支。
追加提交原文允许在当前更改上添加单独提交。
保持关联不要更改分支名，GitLab 用分支名关联 MR。
不写补丁流水账提交消息应描述整体意图，而不是记录每次追加补丁的演进。

处理合并冲突 ​

步骤操作
1检出现有分支。
2基于 Wireshark master 执行 rebase。原文中同时出现 git pull --rebase upstream master 与 git rebase upstream/master 的疑问，需按当前项目说明确认。
3用 git status 找到 Unmerged paths 中的冲突文件。
4在文件中搜索 <<<<<<<、=======、>>>>>>>，编辑为 rebase 后应有的最终内容。
5保存后 git add 冲突文件。
6运行 git rebase --continue，若继续出现冲突则重复处理。
7完成后修正提交并推送到同一分支。

冲突提示示例来自原文：

text
CONFLICT (content): Merge conflict in ui/qt/main_window.ui
Auto-merging ui/qt/main_window.h
Failed to merge in the changes.

合并后清理与测试他人 MR ​

任务原文说明
删除本地分支更改合并到官方 master 后，可删除本地分支。
删除远程分支可从命令行删除个人 GitLab 仓库中的分支，也可在 GitLab Web UI 中删除。
测试他人 MRfetch 对方个人仓库分支到本地，再从 FETCH_HEAD 创建本地分支。
GitLab 辅助每个 merge request 都有 “Check out branch” 按钮，包含类似说明。
text
git branch -d my-branch-name
git push -d downstream my-branch-name

git fetch https://gitlab.com/some-other-user/wireshark.git their-branch-name
git checkout -b other-user-branch-name FETCH_HEAD

撤销更改 ​

状态原文做法
未提交使用 git checkout -- FILES 还原指定文件；不带路径可撤销整个工作树。
已暂存但未提交使用 git reset HEAD FILES 取消暂存，再还原文件。
已进入 master使用 git revert SHA 生成新的还原提交，并走正常审查流程。

回移植到发布分支 ​

情况做法
可干净 cherry-pick在提交页面使用 GitLab 的 Cherry-pick 选项，选择发布分支，并保留创建新 merge request。
不能干净 cherry-pick基于 release-X.Y 创建分支，执行 cherry-pick，修复冲突，构建并测试，再推送并创建面向发布分支的 MR。
目标分支创建 MR 时选择发布分支作为 Target branch。
维护者权限保持允许有合并权限的成员向目标分支提交。
text
git checkout -b my-branch-name upstream/release-X.Y
git cherry-pick -x {commit}
# 修复冲突、构建、测试
git commit
git push downstream HEAD

Git 超简概览 ​

概念原文解释
commit每个提交由唯一 SHA 标识，并指向一个或多个父提交。
历史提交形成一个有向无环图。
tag从文本字符串到提交 SHA 的固定映射。
branch从文本字符串到提交 SHA 的可变映射；新提交会推进分支。
checkout可在工作分支、审查分支和 master 之间切换。
文件关注原文称 GitLab 当时不提供跟踪特定文件变更的方法，并将其描述为常见请求。

从 Gerrit 迁移 ​

主题迁移说明
关联方式变化Gerrit 用提交消息中的 Change-Id 关联更改；GitLab 用个人仓库中的分支名关联 merge request。
commit-msg hookGerrit 使用 commit-msg hook 强制 change ID；迁移到 GitLab 后原文建议移除 .git/hooks/commit-msg。
remotes旧 remote 可能指向 ssh://code.wireshark.org/wireshark；原文示例改用 upstream 指向官方 GitLab 仓库，downstream 指向个人仓库。
未迁移内容原文称 bug 已迁移为 issue，但 Gerrit changes 没有迁移为 GitLab merge request；且当时 Gerrit 系统已下线，无法再迁移。
issue 链接迁移前可用 Bug: 1234 或 Ping-Bug: 1234；GitLab issue 编号需用 # 前缀，可用 closes 自动关闭。
CLI 工具原文列出 lab、git-lab、gitlab-cli 等候选工具，并说明还需更多测试。

来源边界 ​

于 2020-08-11 23:13:08 UTC 从 https://wiki.wireshark.org/Development/SubmittingPatches 导入

相关 Wireshark Wiki 页面 ​

网络分析技术档案

Copyright © 2024 vants.org

皖ICP备12002343号-1