贡献

帮助总是受欢迎的，有很多选择，你可以如何为巩固作出贡献。

我们特别感谢在以下领域的支持：

• 报告问题。

• 修复和响应 Solidity's GitHub issues ，尤其是那些标记为 "good first issue" 这是对外部贡献者的介绍性问题。

• 改进文档。

• 将文档翻译成更多语言。

• 回答其他用户的问题 StackExchange 以及 Solidity Gitter Chat .

• 通过在中提出语言更改或新功能来参与语言设计过程 Solidity forum 并提供反馈。

要开始，您可以尝试 从源代码生成 以便熟悉Solidity的组件和构建过程。此外，精通于稳健地编写智能合约可能会有所帮助。

请注意，此项目发布时 Contributor Code of Conduct .通过参与这个项目-在问题，拉请求，或吉特渠道-你同意遵守它的条款。

团队呼叫

如果您有问题或请求讨论，或有兴趣了解团队和贡献者正在做什么，您可以加入我们的公共团队电话：

• 周一下午3点(CET/CEST)。

• 星期三下午2点CET/CEST。

两次通话都发生在 Jitsi 。

如何报告问题

要报告问题，请使用 GitHub issues tracker .在报告问题时，请提及以下详细信息：

• 坚固版。

• 源代码(如果适用)。

• 操作系统。

• 重现问题的步骤。

• 实际行为与预期行为的对比。

将导致问题的源代码减少到最低限度总是非常有帮助的，有时甚至可以澄清误解。

请求请求工作流

为了捐款，请付 develop 在那里进行分支和更改。您的提交消息应该详细 why 除了 what 你做到了（除非是小小的改变）。

如果你需要从 develop 生成分叉后（例如，要解决潜在的合并冲突），请避免使用 git merge 相反， git rebase 你的分支机构。这将帮助我们更容易地审查您的更改。

此外，如果您正在编写新功能，请确保在下面添加适当的测试用例 test/ （见下文）。

但是，如果您要做较大的更改，请咨询 Solidity Development Gitter channel （与上面提到的不同，这篇文章主要关注编译器和语言开发，而不是语言的使用）。

应将新功能和错误修复添加到 Changelog.md 文件：如果适用，请遵循以前条目的样式。

最后，请确保您尊重 coding style 对于这个项目。此外，即使我们进行CI测试，请在提交请求之前测试您的代码并确保它在本地生成。

谢谢你的帮助！

运行编译器测试

先决条件

要运行所有编译器测试，您可能需要选择性地安装几个依赖项 (evmone ， libz3 ，以及 libhera )。

在MacOS上，一些测试脚本期望安装GNU coreutils。使用HomeBREW可以最容易地实现这一点： brew install coreutils 。

运行测试

坚固性包括不同类型的测试，其中大多数都捆绑到 Boost C++ Test Framework 应用程序 soltest 。正在运行 build/test/soltest 或其包装器 scripts/soltest.sh 对于大多数更改是足够的。

这个 ./scripts/tests.sh 脚本自动执行大多数坚固性测试，包括那些捆绑到 Boost C++ Test Framework 应用程序 soltest (或其包装器 scripts/soltest.sh )，以及命令行测试和编译测试。

测试系统会自动尝试发现 evmone 用于运行语义测试。

这个 evmone 库必须位于 deps 或 deps/lib 相对于当前工作目录、其父目录或其父目录父目录的目录。或者，还可以为 evmone 共享对象可以通过 ETH_EVMONE 环境变量。

evmone 主要用于运行语义和气体测试。如果您尚未安装它，则可以跳过这些测试，方法是将 --no-semantic-tests 标志为 scripts/soltest.sh 。

默认情况下，运行Ewasm测试处于禁用状态，可以通过以下方式显式启用 ./scripts/soltest.sh --ewasm 并要求 hera 将由以下人找到 soltest 。用于定位 hera 库与的相同 evmone ，只是用于指定显式位置的变量被调用 ETH_HERA 。

这个 evmone 和 hera 库和库都应以文件扩展名结尾 .so 在Linux上， .dll 在Windows系统和 .dylib 在MacOS上。

要运行SMT测试， libz3 必须通过以下方式安装库并进行定位 cmake 在编译器配置阶段。

如果 libz3 系统上未安装库，应通过导出禁用SMT测试 SMT_FLAGS=--no-smt 赛前 ./scripts/tests.sh 或运行 ./scripts/soltest.sh --no-smt . 这些测试是 libsolidity/smtCheckerTests 和 libsolidity/smtCheckerTestsJSON .

注解

要获取Soltest运行的所有单元测试的列表，请运行 ./build/test/soltest --list_content=HRF .

为了获得更快的结果，您可以运行一个子集或特定的测试。

要运行测试子集，可以使用筛选器： ./scripts/soltest.sh -t TestSuite/TestName 在哪里 TestName 可以是通配符 * .

或者，例如，运行yul消歧器的所有测试： ./scripts/soltest.sh -t "yulOptimizerTests/disambiguator/*" --no-smt .

./build/test/soltest --help 在所有选项上都有广泛的帮助。

请特别注意：

• show_progress (-p) 要显示测试完成，请执行以下操作：

• run_test (-t) 来运行特定的测试用例，并且

• report-level (-r) 给出一份更详细的报告。

注解

那些在Windows环境下工作的人希望在没有libz3的情况下运行上述基本集。使用Git Bash，可以使用： ./build/test/Release/soltest.exe -- --no-smt . 如果在普通命令提示符下运行此命令，请使用 .\build\test\Release\soltest.exe -- --no-smt .

如果您希望使用gdb进行调试，请确保构建方式与“通常”不同。例如，您可以在您的 build 文件夹：..代码-挡路：：巴斯

cmake-DCMAKE_BUILD_TYPE=调试..制作

这将创建符号，以便在使用 --debug 标志，您可以访问函数和变量，在其中可以中断或打印。

CI运行其他测试（包括 solc-js 以及测试第三方稳固性框架），这些框架需要编译emscripten目标。

编写和运行语法测试

语法测试检查编译器是否为无效代码生成正确的错误消息并正确接受有效代码。它们存储在 tests/libsolidity/syntaxTests 文件夹。这些文件必须包含注释，说明各自测试的预期结果。测试套件编译并对照给定的期望检查它们。

例如： ./test/libsolidity/syntaxTests/double_stateVariable_declaration.sol

open in Remix

contract test {
    uint256 variable;
    uint128 variable;
}
// ----
// DeclarationError: (36-52): Identifier already declared.

语法测试必须至少包含测试中的协定本身，后跟分隔符 // ---- .分隔符后面的注释用于描述预期的编译器错误或警告。数字范围表示发生错误的源位置。如果希望合同编译时不出现任何错误或警告，可以省略分隔符和后面的注释。

在上面的例子中，状态变量 variable 声明了两次，这是不允许的。这会导致 DeclarationError 声明标识符已声明。

这个 isoltest 工具用于这些测试，您可以在 ./build/test/tools/ .它是一个交互式工具，允许使用首选文本编辑器编辑失败的合同。让我们尝试通过删除 variable ：

open in Remix

contract test {
    uint256 variable;
}
// ----
// DeclarationError: (36-52): Identifier already declared.

运行 ./build/test/isoltest 再次导致测试失败：

syntaxTests/double_stateVariable_declaration.sol: FAIL
    Contract:
        contract test {
            uint256 variable;
        }

    Expected result:
        DeclarationError: (36-52): Identifier already declared.
    Obtained result:
        Success

isoltest 打印获得结果旁边的预期结果，并提供编辑、更新或跳过当前合同文件或退出应用程序的方法。

它提供了几个失败测试的选项：

• edit ： isoltest 尝试在编辑器中打开合同，以便您可以对其进行调整。它或者使用命令行上给定的编辑器（如 isoltest --editor /path/to/editor ，在环境变量中 EDITOR 或者只是 /usr/bin/editor （按顺序）。

• update ：更新对正在测试的合同的期望。这将通过删除未满足的期望和添加缺少的期望来更新注释。然后再次运行测试。

• skip ：跳过此特定测试的执行。

• quit ：退出 isoltest .

所有这些选项都适用于当前合同，预计 quit 停止整个测试过程。

自动更新上述测试将其更改为

open in Remix

contract test {
    uint256 variable;
}
// ----

重新运行测试。现在它又一次通过了：

Re-running test case...
syntaxTests/double_stateVariable_declaration.sol: OK

注解

为合同文件选择一个解释其测试内容的名称，例如 double_variable_declaration.sol .不要将多个契约放入单个文件中，除非您正在测试继承或交叉契约调用。每个文件都应该测试新特性的一个方面。

通过AFL运行引信

模糊化是一种在或多或少的随机输入上运行程序以查找异常执行状态（分段错误、异常等）的技术。现代引信很聪明，在输入端进行定向搜索。我们有一个特殊的二进制 solfuzzer 它将源代码作为输入，每当遇到内部编译器错误、分段错误或类似错误时都会失败，但如果代码包含错误，则不会失败。这样，模糊化工具可以在编译器中发现内部问题。

我们主要使用 AFL 用于起毛。您需要从存储库（AFL、AFL-Clang）下载和安装AFL包，或者手动构建它们。接下来，建立稳固性（或只是 solfuzzer 二进制）使用afl作为编译器：

cd build
# if needed
make clean
cmake .. -DCMAKE_C_COMPILER=path/to/afl-gcc -DCMAKE_CXX_COMPILER=path/to/afl-g++
make solfuzzer

在此阶段，您应该能够看到类似以下内容的消息：

Scanning dependencies of target solfuzzer
[ 98%] Building CXX object test/tools/CMakeFiles/solfuzzer.dir/fuzzer.cpp.o
afl-cc 2.52b by <lcamtuf@google.com>
afl-as 2.52b by <lcamtuf@google.com>
[+] Instrumented 1949 locations (64-bit, non-hardened mode, ratio 100%).
[100%] Linking CXX executable solfuzzer

如果没有出现检测消息，请尝试切换指向AFL的clang二进制文件的cmake标志：

# if previously failed
make clean
cmake .. -DCMAKE_C_COMPILER=path/to/afl-clang -DCMAKE_CXX_COMPILER=path/to/afl-clang++
make solfuzzer

否则，在执行时，模糊器停止，并出现错误，表示二进制文件未被检测：

afl-fuzz 2.52b by <lcamtuf@google.com>
... (truncated messages)
[*] Validating target binary...

[-] Looks like the target binary is not instrumented! The fuzzer depends on
    compile-time instrumentation to isolate interesting test cases while
    mutating the input data. For more information, and for tips on how to
    instrument binaries, please see /usr/share/doc/afl-doc/docs/README.

    When source code is not available, you may be able to leverage QEMU
    mode support. Consult the README for tips on how to enable this.
    (It is also possible to use afl-fuzz as a traditional, "dumb" fuzzer.
    For that, you can use the -n option - but expect much worse results.)

[-] PROGRAM ABORT : No instrumentation detected
         Location : check_binary(), afl-fuzz.c:6920

接下来，您需要一些示例源文件。这使得引信更容易发现错误。您可以从语法测试中复制一些文件，也可以从文档或其他测试中提取测试文件：

mkdir /tmp/test_cases
cd /tmp/test_cases
# extract from tests:
path/to/solidity/scripts/isolate_tests.py path/to/solidity/test/libsolidity/SolidityEndToEndTest.cpp
# extract from documentation:
path/to/solidity/scripts/isolate_tests.py path/to/solidity/docs

AFL文档指出语料库（初始输入文件）不应该太大。文件本身不应大于1KB，每个功能最多应该有一个输入文件，所以最好从少量开始。还有一个工具叫做 afl-cmin 它可以修剪导致类似二进制行为的输入文件。

现在运行引信 -m 将内存大小扩展到60 MB）：

afl-fuzz -m 60 -i /tmp/test_cases -o /tmp/fuzzer_reports -- /path/to/solfuzzer

模糊器创建的源文件会导致 /tmp/fuzzer_reports .通常它会发现许多产生相同错误的类似源文件。你可以用这个工具 scripts/uniqueErrors.sh 过滤掉唯一的错误。

Whiskers

Whiskers 字符串模板系统是否类似于 Mustache .编译器在不同的地方使用它来帮助代码的可读性，从而提高代码的可维护性和可验证性。

语法与胡子有很大的不同。模板标记 {{{{ 和 }}}} 被替换 < 和 > 为了帮助分析并避免与 Yul （符号 < 和 > 在内联程序集中无效，而 {{ 和 }} 用于划分块）。另一个限制是列表只能解析一个深度，并且不会重复出现。这在将来可能会改变。

大致规格如下：

任何发生的 <name> 替换为所提供变量的字符串值 name 没有任何转义和迭代替换。一个区域可以用 <#name>...</name> .它被其内容的多个连接替换，就像模板系统中提供的变量集一样，每次替换 <inner> 按其各自的值列出的项。顶级变量也可以在这些区域内使用。

也有条件句的形式 <?name>...<!name>...</name> ，其中模板替换根据布尔参数的值在第一段或第二段递归地继续 name .如果 <?+name>...<!+name>...</+name> 则检查字符串参数是否 name 非空。

文档样式指南

在下面的部分中，您可以找到专门关注文档对Solidity的贡献的样式建议。

英语

使用英语，最好使用英语拼写，除非使用项目或品牌名称。尽量减少使用当地俚语和参考语，使你的语言对所有读者都尽可能清楚。以下是一些帮助参考：

• Simplified technical English

• International English

• British English spelling

注解

虽然官方的稳健性文档是用英语编写的，但还是有社区贡献的 翻译 其他可用的语言版本。请参阅 translation guide 获取有关如何为社区翻译做出贡献的信息。

标题的标题大小写

使用 title case 标题。这意味着在标题中大写所有主要单词，而不是冠词、连词和介词，除非它们以标题开头。

例如，以下各项都是正确的：

• 标题的大小写。

• 标题使用标题大小写。

• 局部和状态变量名。

• 布局顺序。

扩大收缩

对单词使用扩展收缩，例如：

• “不要”而不是“不要”。

• “不能”而不是“不能”。

主动和被动语音

对于教程样式的文档，通常建议使用活动语音，因为它可以帮助读者了解执行任务的人员或内容。然而，由于Solidity文档是教程和参考内容的混合体，因此被动语态有时更适用。

总结如下：

• 使用被动语态作为技术参考，例如语言定义和以太坊虚拟机的内部。

• 在描述如何应用 Solidity 方面的建议时使用主动语态。

例如，下面是被动语态，因为它指定了一个坚实的方面：

函数可以声明 pure 在这种情况下，他们承诺不阅读或修改状态。

例如，在讨论Solidity的应用时，下面是主动语态：

调用编译器时，可以指定如何发现路径的第一个元素，以及路径前缀重新映射。

常用术语

• “函数参数”和“返回变量”，而不是输入和输出参数。

代码示例

CI过程测试所有以 pragma solidity ， contract ， library 或 interface 使用 ./test/cmdlineTests.sh 创建pr时编写脚本。如果要添加新的代码示例，请确保它们可以工作并在创建pr之前通过测试。

确保所有代码示例都以 pragma 合同代码有效的范围最大的版本。例如 pragma solidity >=0.4.0 <0.9.0; 。

运行文档测试

确保您的贡献通过我们的文档测试 ./scripts/docs.sh 它安装文档所需的依赖项，并检查是否存在任何问题，如断开的链接或语法问题。

坚实的语言设计

要积极参与语言设计过程，并分享您对未来坚实的想法，请加入 Solidity forum 。

坚固性论坛是提出和讨论新的语言功能及其在现有功能构思或修改的早期阶段实施的场所。

一旦提案变得更加具体，它们的实施也将在 Solidity GitHub repository 以发行的形式。

除了论坛和问题讨论外，我们还定期主持语言设计讨论电话会议，详细讨论选定的主题、问题或功能实现。这些电话会议的邀请是通过论坛共享的。

我们还在论坛上分享反馈、调查和其他与语言设计相关的内容。

如果您想了解团队的立场或实现新功能的情况，可以关注 Solidity Github project 。设计待办事项中的问题需要进一步说明，并将在语言设计会议或常规团队会议中讨论。通过从缺省分支进行更改，您可以查看下一个突破性版本即将进行的更改 (develop) to the breaking branch 。

对于特殊情况和问题，您可以通过 Solidity-dev Gitter channel ，一个专门的聊天室，用于讨论Solidity编译器和语言开发。

我们很高兴听到您对我们如何改进语言设计过程，使之更具协作性和透明度的想法。