原文网址：https://github.com/facebook/rocksdb/wiki/RocksDB-Contribution-Guide

(有道)

Ways to Contribute

Other than contributing code changes, there're lots of other ways to contribute to the RocksDB community. For example:
除了修改代码，我们还可以通过其他方式为RocksDB社区做出贡献。例如:

• Add or update document, our github wiki is open for anyone to edit;
  添加或更新文档，我们的github wiki是开放给任何人编辑;
• Answer questions on the user group, stackoverflow, facebook group;
  回答user group、stackoverflow、facebook group上的问题;
• Report issue with detailed information, if possible attache a test with that;
  提交详细信息的报告，如果可能的话，附上测试报告;
• Investigate and fix an issue; We would appreciate if you could help to reproduce the issue, which is typically the hardest part. If you're looking for an open issue to work on, here is the list of issues up for grab;
  调查和解决问题;我们将感激如果你能帮助再现这个问题，这通常是最难的部分。如果你正在寻找一个有待解决的问题，这里有一个问题列表(可获取)(https://github.com/facebook/rocksdb/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aup-for-grabs+no%3Aassignee)
• Review and test a PR. We have some PRs pending review, your reviewing or test can reduce the reviewing load on us;
  对PR进行审核和测试。我们有一些PR正在审核中，您的审核或测试可以减少我们的审核负担;
• Submit new feature request or implementation. We welcome any feature suggestions, for new feature implementation, please create an issue with the design proposal first. It can help to get more engagement and discussion before reviewing your implementation;
  提交新特性请求或实现。我们欢迎任何功能建议，对于新功能的实现，请首先创建一个问题与设计建议。这有助于在审查你的实施之前获得更多的参与和讨论;
• Help ongoing features development, here is list of new features that's actively developing, help us to complete the feature development.
  帮助正在进行的功能开发，以下是正在积极开发的新功能，帮助我们完成功能开发。

Before Code Contribution

Before contributing to RocksDB, please make sure that you are able to sign CLA. Your change will not be merged unless you have proper CLA signed. See https://code.facebook.com/cla for more information.
在向RocksDB提交内容之前，请确保你能够签署CLA。您的更改将不会被合并，除非您有适当的CLA签署。更多信息请参见https://code.facebook.com/cla。

Basic Development Workflow

As most open-source projects in github, RocksDB contributors work on their fork, and send pull requests to RocksDB’s facebook repo. After a reviewer approves the pull request, a RocksDB team member at Facebook will merge it.
就像github上的大多数开源项目一样，RocksDB的开发者也致力于自己的fork项目，并向RocksDB的facebook repo发送pull请求。在审查员批准该请求后，RocksDB的Facebook团队成员便会将其合并。

How to Run Unit Tests

Build Systems

RocksDB uses gtest. The makefile used for GNU make has some supports to help developers run all unit tests in parallel, which will be introduced below. If you use cmake, you can run the tests with ctest.
RocksDB使用gtest。使用的GNU make 的makefile特性，可以帮助开发人员并行运行所有单元测试，下面将介绍这些内容。如果你使用cmake，你可以使用' ctest '运行测试。

Run Unit Tests In Parallel

In order to run unit tests in parallel, first install GNU parallel on your host, and run
为了并行运行单元测试，首先要在主机上安装GNU parallel，然后运行

make all check [-j] 

You can specify number of parallel tests to run using environment variable J=1, for example:
可以使用环境变量' J=1 '指定要运行的并行测试数量，例如:

make J=64 all check [-j]

If you switch between release and debug build, normal or lite build, or compiler or compiler options, call make clean first. So here is a safe routine to run all tests:
如果你在发布版和调试版、普通版或精简版、编译器或编译器选项之间切换，请先调用“make clean”。所以这里有一个运行所有测试的安全程序:

make clean
make J=64 all check [-j]

Debug Single Unit Test Failures

RocksDB uses gtest. You can run specific unit test by running the test binary that contains it. If you use GNU make, the test binary will be just under your checkpoint. For example, test DBBasicTest.OpenWhenOpen is in binary db_basic_test, so just run
RocksDB使用gtest。您可以通过运行包含单元测试的测试二进制文件来运行特定的单元测试。如果您使用GNU make，测试二进制文件将位于检查点之下。例如，test ' DBBasicTest。OpenWhenOpen '是二进制' db_basic_test '，所以运行

./db_basic_test

will run all tests in the binary.
将运行二进制文件中的所有测试。

gtest provides some useful command line parameters, and you can see them by calling --help:
Gtest提供了一些有用的命令行参数，你可以通过调用'——help '来查看它们:

./db_basic_test --help

Here are some frequently used ones:
下面是一些常用内容:

Run subset of tests using --gtest_filter. If you only want to run DBBasicTest.OpenWhenOpen, call
使用'——gtest_filter '运行测试的子集。如果你只想运行' DBBasicTest。OpenWhenOpen’,调用

./db_basic_test --gtest_filter=“*DBBasicTest.OpenWhenOpen*”

By default, the test DB created by tests is cleared up even if test fails. You can try to preserve it by using --gtest_throw_on_failure. If you want to stop the debugger when assert fails, specify --gtest_break_on_failure. KEEP_DB=1 environment variable is another way to preserve the test DB from being deleted at the end of a unit-test run, irrespective of whether the test fails or not:
默认情况下，即使测试失败，测试创建的测试DB也会被清除。你可以使用'——gtest_throw_on_failure '来保存它。如果你想在assert失败时停止调试器，请指定'——gtest_break_on_failure '。' KEEP_DB=1 '环境变量是另一种方法来保持测试DB在单元测试运行结束时不被删除，无论测试是否失败:

KEEP_DB=1 ./db_basic_test --gtest_filter=DBBasicTest.Open

By default, the temporary test files will be under /tmp/rocksdbtest-<number>/ (except when running in parallel they are under /dev/shm). You can override the location by using environment variable TEST_TMPDIR. For example:
默认情况下，临时测试文件将放在' /tmp/rocksdbtest-<number>/ '目录下(除非它们在/dev/shm目录下并行运行)。您可以使用环境变量' TEST_TMPDIR '重写该位置。例如:

TEST_TMPDIR=/dev/shm/my_dir ./db_basic_test

Java Unit Tests

Sometimes we need to run Java tests too. Run
有时我们也需要运行Java测试。运行

make jclean rocksdbjava jtest

You can put -j but sometimes it causes problem. Try to remove -j if you see problems.
你可以用' -j '，但有时它会引起问题。如果发现问题，尝试删除' -j '。

Some other build flavors

For more complicated code changes, we ask contributors to run more build flavors before sending the code review. The makefile for GNU make has better pre-defined support for it, although it can be manually done in CMake too.
对于更复杂的代码更改，我们要求贡献者在发送代码审查之前运行更多构建风格。GNU make的makefile对它有更好的预定义支持，尽管它也可以在CMake中手动完成。

To build with AddressSanitizer (ASAN), set environment variable COMPILE_WITH_ASAN:
使用AddressSanitizer (ASAN)构建，设置环境变量' COMPILE_WITH_ASAN ':

COMPILE_WITH_ASAN=1 make all check -j

To build with ThreadSanitizer (TSAN), set environment variable COMPILE_WITH_TSAN:
要使用ThreadSanitizer (TSAN)构建，请设置环境变量' COMPILE_WITH_TSAN ':

COMPILE_WITH_TSAN=1 make all check -j

To run all valgrind tests:
要运行所有的“valgrind测试”:

make valgrind_test -j

To run _UndefinedBehaviorSanitizer (UBSAN), set environment variable COMPILE_WITH_UBSAN:
要运行_UndefinedBehaviorSanitizer (UBSAN)，设置环境变量' COMPILE_WITH_UBSAN ':

COMPILE_WITH_UBSAN=1 make all check -j

To run llvm's analyzer, run
要运行“llvm”的分析器，请运行

make analyze

Code Style

RocksDB follows Google C++ Style: https://google.github.io/styleguide/cppguide.html . We limit each line to 80 characters.
RocksDB则遵循Google c++ Style: https://google.github.io/styleguide/cppguide.html。我们将每行限制为80个字符。

Some formatting can be done by a formatter by running
一些格式化可以由格式化程序通过运行来完成

build_tools/format-diff.sh

or simply make format if you use GNU make. If you lack of dependencies to run it, the script will print out instructions for you to install them.
如果你使用GNU make，可以使用' make format '。如果缺少运行它的依赖项，脚本将打印出安装它们的说明。

Requirements Before Sending a Pull Request

HISTORY.md

Consider updating HISTORY.md to mention your change, especially if it's a bug fix, public API change or an awesome new feature.
考虑更新的历史。特别是当它是一个bug修复，公共API的改变或一个很棒的新特性时。

Pull Request Summary

We recommend a "Test Plan:" section is included in the pull request summary, which introduces what testing is done to validate the quality and performance of the change.
我们建议在拉请求摘要中包含一个“测试计划:”部分，它介绍了为了验证变更的质量和性能所做的测试。

Add Unit Tests

Almost all code changes need to go with changes in unit tests for validation. For new features, new unit tests or tests scenarios need to be added even if it has been validated manually. This is to make sure future contributors can rerun the tests to validate their changes don't cause problem with the feature.
几乎所有的代码更改都需要更改单元测试以进行验证。对于新特性，需要添加新的单元测试或测试场景，即使它已经手工验证。这是为了确保将来的贡献者可以重新运行测试，以验证他们的更改不会导致特性出现问题。

Simple Changes

Pull requests for simple changes can be sent after running all unit tests with any build favor and see all tests pass. If any public interface is changed, or Java code involved, Java tests also need to be run.
简单更改的Pull请求可以在运行所有单元测试后发送，并查看所有测试的通过情况。如果更改了任何公共接口，或者涉及Java代码，则还需要运行Java测试。

Complex Changes

If the change is complicated enough, ASAN, TSAN and valgrind need to be run on your local environment before sending the pull request. If you run ASAN with higher version of llvm with covers almost all the functionality of valgrind, valgrind tests can be skipped.
如果更改足够复杂，则需要在发送pull请求之前在本地环境中运行ASAN、TSAN和valgrind。如果使用包含valgrind几乎所有功能的更高版本的llvm运行ASAN，那么可以跳过valgrind测试。
It may be hard for developers who use Windows. Just try to use the best equivalence tools available in your environment.
对于使用Windows的开发人员来说可能很难。尽量使用环境中可用的最好的等价工具。

Changes with Higher Risk or Some Unknowns

For changes with higher risks, other than running all tests with multiple flavors, a crash test cycle (see [[Stress Test]]) needs to be executed and see no failure. If crash test doesn't cover the new feature, consider to add it there.
对于风险较高的更改，除了使用多种方式运行所有测试外，还需要执行一个崩溃测试周期(请参见[[压力测试]])，并且不会看到任何失败。如果碰撞测试没有涵盖新功能，可以考虑添加它。
To run all crash test, run
要运行所有碰撞测试，运行

make crash_test -j
make crash_test_with_atomic_flush -j

If you can't use GNU make, you can manually build db_stress binary, and run script:
如果你不能使用GNU make，你可以手动构建db_stress二进制文件，然后运行script:

  python -u tools/db_crashtest.py whitebox
  python -u tools/db_crashtest.py blackbox
  python -u tools/db_crashtest.py --simple whitebox
  python -u tools/db_crashtest.py --simple blackbox
  python -u tools/db_crashtest.py --cf_consistency blackbox
  python -u tools/db_crashtest.py --cf_consistency whitebox 

Performance Improvement Changes

For changes that might impact performance, we suggest normal benchmarks are run to make sure there is no regression. Depending the actual performance, you may choose to run against a database backed by disks, or memory-backed file systems. Explain in the pull request summary why the performance environment is chosen, if it is not obvious. If the change is to improve performance, bring at least one benchmark test case that favors the improvement and show the improvements.
对于可能影响性能的更改，我们建议运行正常的基准测试，以确保没有回归。根据实际性能，您可以选择在由磁盘支持的数据库或内存支持的文件系统上运行。如果不明显，请在pull request摘要中解释为什么选择性能环境。如果更改是为了提高性能，那么至少要带来一个支持改进的基准测试用例，并显示这些改进。