From 4358afc62f8cfe1065293ac62ef2752d9e9e18b4 Mon Sep 17 00:00:00 2001 From: QGrain Date: Fri, 12 Jul 2024 00:04:30 +0800 Subject: [PATCH 1/2] finish translating contributing.md --- sources/syzkaller/contributing.md | 145 ++++++++++++++---------------- 1 file changed, 68 insertions(+), 77 deletions(-) diff --git a/sources/syzkaller/contributing.md b/sources/syzkaller/contributing.md index 91f0141..820ef81 100644 --- a/sources/syzkaller/contributing.md +++ b/sources/syzkaller/contributing.md @@ -1,78 +1,78 @@ --- -status: translating +status: translated title: "How to contribute to syzkaller" author: Syzkaller Community collector: jxlpzqc collected_date: 20240314 translator: QGrain +translated_date: 20240712 link: https://github.com/google/syzkaller/blob/master/docs/contributing.md --- -# How to contribute to syzkaller +# 如何向 syzkaller 项目贡献 -If you want to contribute to the project, feel free to send a pull request following the [guidelines](contributing.md#guidelines) below. +如果你想为该项目做出贡献，请按照下面的[指南](contributing.md#guidelines)发送拉取请求。 -In case this is your first pull request to syzkaller, you will need to [sign Google CLA](https://cla.developers.google.com/) -and add yourself to [AUTHORS](/AUTHORS)/[CONTRIBUTORS](/CONTRIBUTORS) files in the first commit. +如果这是你第一次向 syzkaller 提交拉取请求，你需要[签署 Google CLA](https://cla.developers.google.com/)。 +并在第一次提交时将自己添加到 [AUTHORS](/AUTHORS)/[CONTRIBUTORS](/CONTRIBUTORS) 文件中。 -## What to work on +## 工作内容 -Extending/improving [system call descriptions](syscall_descriptions.md) is always a good idea. +扩展/改进 [系统调用描述](syscall_descriptions.md) 一直是个好主意。 -Unassigned issues from the [bug tracker](https://github.com/google/syzkaller/issues) are worth doing, but some of them might be complicated. +[错误跟踪器](https://github.com/google/syzkaller/issues) 中未分配的议题是值得去做的，但其中有些议题可能比较复杂。 -To contribute code or syscall descriptions, at the very least you need to be able to build and run syzkaller, see the instructions [here](/docs/setup.md). +要贡献代码或系统调用描述，至少需要能够构建并运行 syzkaller，请参阅[此处](/docs/setup.md)的说明。 -## Guidelines +## 指南 -If you want to work on something non-trivial, please briefly describe it on the -[syzkaller@googlegroups.com](https://groups.google.com/forum/#!forum/syzkaller) mailing list first, -so that there is an agreement on the high level approach/design and no duplication of work between contributors. +如果您想做一些并不微小的事情，请先在 [syzkaller@googlegroups.com](https://groups.google.com/forum/#!forum/syzkaller) 邮件列表上简要描述，以便在高层面的方法/设计上达成一致，且避免贡献者之间的重复工作。 -Split large changes into smaller, logically cohesive commits. Small commits are much easier and faster to review and iterate on. +将大改动拆分成逻辑上连贯的小提交。小的提交更容易、更快地进行审核和迭代。 -Everything that can be reasonably tested should be tested. +所有可以合理测试的内容都应进行测试。 -Provide enough documentation for other users to use the new feature. +为其他用户使用新功能提供足够的文档。 -Keep the style of the code, tests, comments, docs, log/error messages consistent with the existing style. +保持代码、测试、注释、文档、日志/错误信息的风格与现有风格一致。 -Continuous Integration (CI) system runs a number of tests and some [opinionated] style checks. They need to pass. -You can test locally with `make presubmit`, if you don't have some prerequisites installed, -you may use `syz-env` (see below). +持续集成（CI）系统会运行大量测试和一些 [意见] 式检查。它们需要通过。你可以使用 `make presubmit` 进行本地测试，如果没有安装某些先决条件，你可以尝试使用 `syz-env` （见下文）。 -### Commits +### 提交 -Commit messages should follow the following template: +提交信息应遵循以下模板： ``` -dir/path: one-line description - -Extended multi-line description that includes -the problem you are solving and how it is solved. +dir/path: 单行描述 +<空行> +扩展的多行描述，包括 +您要解决的问题以及如何解决问题。 ``` `dir/path` is a relative path to the main dir this commit changes (look at examples in the [commit history](https://github.com/google/syzkaller/commits/master)). -If several packages/dirs are significantly affected, then the following format is allowed: +If several packages/dirs are significantly affected, then the following format is allowed:是本次提交更改的主目录的相对路径。（参见 [commit history](https://github.com/google/syzkaller/commits/master) 中的示例）。如果多个软件包/目录受到重大影响，则允许使用以下格式： ``` -dir1/path1, dir2/path2: one-line description +dir1/path1, dir2/path2: 单行描述 ``` -Though, dirs should not be included if they have only minor changes. -For pervasive changes the following format is allowed: +不过，如果目录仅有细微改动，则不应包括在内。 +对于普遍变化，可以使用以下格式： ``` -all: one-line description +all: 单行描述 ``` -Please pay attention to punctuation. In particular: +请注意标点符号，特别是： -- `one-line description` should *not* start with a Capital letter. -- There is *no dot* at the end of `one-line description`. -- `Extended multi-line description` is full English sentences with Capital letters and dots. +- `单行描述` *不*应该以大写字母开头。 +- `单行描述` 末尾*没有点*。 +- `扩展的多行描述` 是带有大写字母和圆点的全英文句子。 -Commit message line length is limited to 120 characters. +提交信息行长度限制为 120 个字符。 -Also: +还有: + +- 如果您的提交修复了一个议题，请在提交信息中加入 `Fixes #NNN` 行（其中 `NNN` 是议题编号）。这将自动关闭议题。如果您需要提及议题，请添加 `Update #NNN`。 +- 对于系统调用描述，`*.const` 文件应该与 `*.txt` 的更改在同一提交中签入。 - If your commit fixes an issue, please include `Fixes #NNN` line into commit message (where `NNN` is the issue number). This will auto-close the issue. If you need to mention @@ -80,25 +80,23 @@ an issue without closing it, add `Update #NNN`. - For syscall descriptions `*.const` files are checked-in with the `*.txt` changes in the same commit. -### Pull requests +### 拉取请求 + -- Rebase your working branch onto the master branch before sending a pull request to avoid merge conflicts. -- Run `make presubmit` and ensure that it passes before sending a PR. - It may require some additional packages to be installed (try `sudo make install_prerequisites`). -- Provide a brief high-level description in the pull request title. - The pull request text is mostly irrelevant, all the details should be in the commit messages. -- If you're asked to add some fixes to your pull request, please squash the fixes into the old commits. +- 在发送拉取请求前，将你的工作分支变基到主分支以避免合并冲突。 +- 运行 `make presubmit` 并确保通过后再发送 PR。 + 可能需要安装一些额外的软件包（请尝试 `sudo make install_prerequisites`）。 +- 在拉取请求标题中提供简短的高级描述。 + 拉取请求文本大多无关紧要，所有细节都应在提交信息中说明。 +- 如果您被要求在拉取请求中添加一些修正，请将修正压入旧提交中。 -### How to create a pull request on Github +### 如何在 Github 上创建一个拉取请求 -- First, you need an own git fork of syzkaller repository. Navigate to -[github.com/google/syzkaller](https://github.com/google/syzkaller) and press `Fork` button in the top-right corner of -the page. This will create `https://github.com/YOUR_GITHUB_USERNAME/syzkaller` repository. +- 首先，您需要一个自己的 syzkaller 仓库的 git fork。导航到 [github.com/google/syzkaller](https://github.com/google/syzkaller)，然后点击页面右上角的 "Fork "按钮。这将创建 `https://github.com/YOUR_GITHUB_USERNAME/syzkaller` 仓库。 -- Checkout main syzkaller repository if you have not already. The simplest way to do it is to run `git clone https://github.com/google/syzkaller`, this will checkout -the repository in the current working directory. -- Remember to `export PATH=$GOPATH/bin:$PATH` if you have not already. -- Then add your repository as an additional origin: +- 请切换到 syzkaller 主版本库，如果尚未进行这一步。最简单的方法是运行 `git clone https://github.com/google/syzkaller`，这将在当前工作目录中切换到该仓库。 +- 请记得 `export PATH=$GOPATH/bin:$PATH`，如果尚未导出 PATH 到环境变量。 +- 然后将您的仓库添加为附加源： ```shell cd syzkaller @@ -107,55 +105,48 @@ the repository in the current working directory. git checkout -b my-branch my-origin/master ``` -This adds git origin `my-origin` with your repository and checks out new branch `my-branch` based on `master` branch. +这会将您的仓库添加到 git origin `my-origin`，并基于 `master` 分支创建并切换新的分支 `my-branch` 。 -- Change/add files as necessary. -- Commit changes locally. For this you need to run `git add` for all changed files, e.g. `git add sys/linux/sys.txt`. You can run `git status` to see what files were changed/created. When all files are added (`git status` shows no files in `Changes not staged for commit` section and no relevant files in `Untracked files` section), run `git commit` and enter commit description in your editor. -- Run tests locally (`make install_prerequisites` followed by `make presubmit`). -- Push the commit to your fork on github with `git push my-origin my-branch`. -- Navigate to [github.com/google/syzkaller](https://github.com/google/syzkaller) and you should see green `Compare & pull request` button, press it. Then press `Create pull request`. Now your pull request should show up on [pull requests page](https://github.com/google/syzkaller/pulls). -- If you don't see `Create pull request` button for any reason, you can create pull request manually. For that navigate to [pull requests page](https://github.com/google/syzkaller/pulls), press `New pull request`, then `compare across forks` and choose `google/syzkaller`/`master` as base and `YOUR_GITHUB_USERNAME/syzkaller`/`my-branch` as compare and press `Create pull request`. -- If you decided to rebase commits in `my-branch` (e.g. to rebase them onto updated master) after you created a pull-request, you will need to do a force push: `git push -f my-origin my-branch`. +- 根据需要更改/添加文件。 +- 将更改提交到本地。为此，你需要对所有更改的文件运行 `git add`，例如 `git add sys/linux/sys.txt`。你可以运行 `git status` 查看有哪些文件被修改/创建。当所有文件都添加完毕后（`git status` 显示 `Changes not staged for commit` 部分没有文件，并且 `Untracked files` 部分没有相关文件），运行 `git commit` 并在你的编辑器中输入提交描述。 +- 在本地运行测试（`make install_prerequisites`，然后执行 `make presubmit`）。 +- 使用 `git push my-origin my-branch` 将提交推送到 github 上的分叉。 +- 导航至 [github.com/google/syzkaller](https://github.com/google/syzkaller)，你会看到绿色的 `Compare & pull request` 按钮，按下它。然后按 `创建拉取请求`。现在你的拉取请求应该会出现在[拉取请求页面](https://github.com/google/syzkaller/pulls)上。 +- 如果你由于任何原因看不到 `创建拉取请求` 按钮，你可以手动创建拉取请求。为此，请导航至 [pull requests page](https://github.com/google/syzkaller/pulls)，按下 `New pull request`，然后按下 `compare across forks` 并选择 `google/syzkaller`/`master` 作为基础，选择 `YOUR_GITHUB_USERNAME/syzkaller`/`my-branch` 作为比较，然后按下 `Create pull request`。 +- 如果在创建了拉取请求后，你决定对 `my-branch` 中的提交进行变基（例如，将它们变基到更新的 master 上），则需要执行一次强制推送：`git push -f my-origin my-branch`。 -### Using syz-env +### 使用 syz-env -Developing syzkaller requires a number of tools installed (Go toolchain, C/C++ cross-compilers, golangci-lint, etc). -Installing all of them may be cumbersome, e.g. due broken/missing packages. -[syz-env](/tools/syz-env) provides a working hermetic development environment based on a Docker container. -If you don't yet have Docker installed, see [documentation](https://docs.docker.com/engine/install), -in particular regarding enabling [sudo-less](https://docs.docker.com/engine/install/linux-postinstall) -Docker (Googlers see go/docker). +开发 syzkaller 需要安装大量工具（Go 工具链、C/C++ 交叉编译器、golangci-lint 等）。安装所有这些工具可能会很麻烦，例如由于软件包损坏/缺失。[syz-env](/tools/syz-env) 提供了一个基于 Docker 容器的密封开发环境。如果尚未安装 Docker，请参阅[文档](https://docs.docker.com/engine/install)、特别是关于启用 [sudo-less](https://docs.docker.com/engine/install/linux-postinstall) 的 Docker（Googlers 参见 go/docker）。 -It's recommended to create an alias for `syz-env` script: +建议为 `syz-env` 脚本创建别名： ``` alias syz-env="$(go env GOPATH)/src/github.com/google/syzkaller/tools/syz-env" ``` -Then it can be used to wrap almost any make invocation as: +然后，几乎所有的 make 调用都可以用它来封装： ``` syz-env make format syz-env make presubmit syz-env make extract SOURCEDIR=$(readlink -f ~/linux) ``` -Or other commands/scripts, e.g.: +或其他命令/脚本，例如： ``` syz-env go test -short ./pkg/csource ``` -Or you may run the shell inside of the container with just `syz-env` and look around. +或者，你也可以只使用 `syz-env` 来在容器内运行 shell 并四处看看。 -To update `syz-env` container to the latest version do: +要将 `syz-env` 容器更新到最新版本，请执行以下操作： ``` bash docker pull gcr.io/syzkaller/env ``` -If you do not have access to the `gcr.io` registry, there is also a mirror in `docker.pkg.github.com` registry. -In order to use it, you need to -[authenticate Docker](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages) -with your Github account with: +如果你无法访问 `gcr.io` 登记处，在 `docker.pkg.github.com` 登记处中也有一个镜像。要使用它，你需要使用你的 Github 账户来[验证 Docker](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages)： + ``` docker login https://docker.pkg.github.com ``` -and then pull the image and retag it to the name expacted by `syz-env`: +然后拉取镜像，并将其重新标记为 `syz-env` 所期望的名称： ``` docker pull docker.pkg.github.com/google/syzkaller/env docker tag docker.pkg.github.com/google/syzkaller/env gcr.io/syzkaller/env From 7d1b970f583ccd6fb547468ec8b3a6be2e4cc20c Mon Sep 17 00:00:00 2001 From: QGrain Date: Sat, 13 Jul 2024 15:07:28 +0800 Subject: [PATCH 2/2] =?UTF-8?q?unified=20use=20of=20=E5=88=9B=E5=BB=BA?= =?UTF-8?q?=E6=8B=89=E5=8F=96=E8=AF=B7=E6=B1=82=20rather=20than=20English?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sources/syzkaller/contributing.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/sources/syzkaller/contributing.md b/sources/syzkaller/contributing.md index 820ef81..6c34712 100644 --- a/sources/syzkaller/contributing.md +++ b/sources/syzkaller/contributing.md @@ -13,7 +13,7 @@ link: https://github.com/google/syzkaller/blob/master/docs/contributing.md 如果你想为该项目做出贡献，请按照下面的[指南](contributing.md#guidelines)发送拉取请求。 -如果这是你第一次向 syzkaller 提交拉取请求，你需要[签署 Google CLA](https://cla.developers.google.com/)。 +如果这是你第一次向 syzkaller 提交拉取请求，你需要[签署 Google CLA](https://cla.developers.google.com/)， 并在第一次提交时将自己添加到 [AUTHORS](/AUTHORS)/[CONTRIBUTORS](/CONTRIBUTORS) 文件中。 ## 工作内容 @@ -32,7 +32,7 @@ link: https://github.com/google/syzkaller/blob/master/docs/contributing.md 所有可以合理测试的内容都应进行测试。 -为其他用户使用新功能提供足够的文档。 +为了其他用户能方便地使用新特性，请提供足够的文档说明。 保持代码、测试、注释、文档、日志/错误信息的风格与现有风格一致。 @@ -49,14 +49,12 @@ dir/path: 单行描述 您要解决的问题以及如何解决问题。 ``` -`dir/path` is a relative path to the main dir this commit changes -(look at examples in the [commit history](https://github.com/google/syzkaller/commits/master)). -If several packages/dirs are significantly affected, then the following format is allowed:是本次提交更改的主目录的相对路径。（参见 [commit history](https://github.com/google/syzkaller/commits/master) 中的示例）。如果多个软件包/目录受到重大影响，则允许使用以下格式： +`dir/path` 是本次提交更改的主目录的相对路径。（参见 [commit history](https://github.com/google/syzkaller/commits/master) 中的示例）。如果多个软件包/目录发生重大改动，则允许使用以下格式： ``` dir1/path1, dir2/path2: 单行描述 ``` 不过，如果目录仅有细微改动，则不应包括在内。 -对于普遍变化，可以使用以下格式： +对于普遍的更改，可以使用以下格式： ``` all: 单行描述 ``` @@ -74,12 +72,6 @@ all: 单行描述 - 如果您的提交修复了一个议题，请在提交信息中加入 `Fixes #NNN` 行（其中 `NNN` 是议题编号）。这将自动关闭议题。如果您需要提及议题，请添加 `Update #NNN`。 - 对于系统调用描述，`*.const` 文件应该与 `*.txt` 的更改在同一提交中签入。 -- If your commit fixes an issue, please include `Fixes #NNN` line into commit message -(where `NNN` is the issue number). This will auto-close the issue. If you need to mention -an issue without closing it, add `Update #NNN`. -- For syscall descriptions `*.const` files are checked-in with the `*.txt` changes -in the same commit. - ### 拉取请求 @@ -111,13 +103,13 @@ in the same commit. - 将更改提交到本地。为此，你需要对所有更改的文件运行 `git add`，例如 `git add sys/linux/sys.txt`。你可以运行 `git status` 查看有哪些文件被修改/创建。当所有文件都添加完毕后（`git status` 显示 `Changes not staged for commit` 部分没有文件，并且 `Untracked files` 部分没有相关文件），运行 `git commit` 并在你的编辑器中输入提交描述。 - 在本地运行测试（`make install_prerequisites`，然后执行 `make presubmit`）。 - 使用 `git push my-origin my-branch` 将提交推送到 github 上的分叉。 -- 导航至 [github.com/google/syzkaller](https://github.com/google/syzkaller)，你会看到绿色的 `Compare & pull request` 按钮，按下它。然后按 `创建拉取请求`。现在你的拉取请求应该会出现在[拉取请求页面](https://github.com/google/syzkaller/pulls)上。 -- 如果你由于任何原因看不到 `创建拉取请求` 按钮，你可以手动创建拉取请求。为此，请导航至 [pull requests page](https://github.com/google/syzkaller/pulls)，按下 `New pull request`，然后按下 `compare across forks` 并选择 `google/syzkaller`/`master` 作为基础，选择 `YOUR_GITHUB_USERNAME/syzkaller`/`my-branch` 作为比较，然后按下 `Create pull request`。 +- 导航至 [github.com/google/syzkaller](https://github.com/google/syzkaller)，你会看到绿色的 `比较 & 拉取请求` 按钮，按下它。然后按 `创建拉取请求`。现在你的拉取请求应该会出现在[拉取请求页面](https://github.com/google/syzkaller/pulls)上。 +- 如果你由于任何原因看不到 `创建拉取请求` 按钮，你可以手动创建拉取请求。为此，请导航至[拉取请求页面](https://github.com/google/syzkaller/pulls)，按下 `新的拉取请求`，然后按下 `横叉比较` 并选择 `google/syzkaller`/`master` 作为基础，选择 `YOUR_GITHUB_USERNAME/syzkaller`/`my-branch` 作为比较，然后按下 `创建拉取请求`。 - 如果在创建了拉取请求后，你决定对 `my-branch` 中的提交进行变基（例如，将它们变基到更新的 master 上），则需要执行一次强制推送：`git push -f my-origin my-branch`。 ### 使用 syz-env -开发 syzkaller 需要安装大量工具（Go 工具链、C/C++ 交叉编译器、golangci-lint 等）。安装所有这些工具可能会很麻烦，例如由于软件包损坏/缺失。[syz-env](/tools/syz-env) 提供了一个基于 Docker 容器的密封开发环境。如果尚未安装 Docker，请参阅[文档](https://docs.docker.com/engine/install)、特别是关于启用 [sudo-less](https://docs.docker.com/engine/install/linux-postinstall) 的 Docker（Googlers 参见 go/docker）。 +开发 syzkaller 需要安装大量工具（Go 工具链、C/C++ 交叉编译器、golangci-lint 等）。安装所有这些工具可能会很麻烦，例如由于软件包损坏/缺失。[syz-env](/tools/syz-env) 提供了一个基于 Docker 容器的密封开发环境。如果尚未安装 Docker，请参阅[文档](https://docs.docker.com/engine/install)，特别是关于启用 [sudo-less](https://docs.docker.com/engine/install/linux-postinstall) 的 Docker（Googlers 参见 go/docker）。 建议为 `syz-env` 脚本创建别名： ``` @@ -133,7 +125,7 @@ syz-env make extract SOURCEDIR=$(readlink -f ~/linux) ``` syz-env go test -short ./pkg/csource ``` -或者，你也可以只使用 `syz-env` 来在容器内运行 shell 并四处看看。 +或者，你也可以只使用 `syz-env` 来在容器内运行 shell 并进行查看。 要将 `syz-env` 容器更新到最新版本，请执行以下操作：