项目代码贡献者指南

这是一个项目,临时或定期,代码贡献者指南。

代码贡献。

代码贡献可以是bug修复或新特性。两者的过程相同,因此将在本节中一起讨论。

做出改变

  • 创建一个主题分支,从中创建您的工作基础。

  • 你通常应该把你的主题分支建立在主分支的基础上。

  • 要快速创建主题分支,请执行以下操作: git checkout -b my-topic-branch

  • 提交逻辑单元。

  • 用空格键检查不必要的空格 git diff --check 在提交之前。

  • 确保提交消息位于 proper format .

  • 确保已为更改添加了必要的测试。

  • 确保所有测试都通过

提交变化

  • 将更改推送到存储库分支中的主题分支。

  • 向OSGeo组织中的PROJ存储库提交pull请求。

  • 如果拉取请求修复/引用了一个问题,请在拉取请求中包含该问题编号。例如:

Wiz the bang

Fixes #123.
  • 项目开发人员将查看您的补丁并采取适当的操作。

编码约定

程序设计语言

PROJ最初是在ANSI C中开发的,今天PROJ大部分是在C++ 11中开发的,代码基础的几个部分仍然是C。代码库的大部分旧部分是有效的C,有一些修改,以便它更好地编译为C++。

编码风格

作为C++开始其生命周期的代码库的部分使用 clang-format 使用脚本 scripts/reformat_cpp.sh 。这主要包含在 src/iso19111/ 但其他一些人 .cpp -文件也包括在内。

对于代码库的其余部分,它的起源是C,我们不强制任何特定的编码风格,但请尽量保持它的简单性。如果改进现有的代码,请尽量符合当地周围代码的风格。

空白

在整个项目代码库中,您将看到不同的空格用法。一般规则是在当前编辑的文件中保留任何形式的空白。如果文件混合了制表符和空格,请在进行任何其他更改之前在单独的提交中将制表符转换为空格。这使得在评估更改的代码时更容易看到差异中的更改。新文件应使用空格作为空白。

工具

C++代码的重新格式化

中的脚本 scripts/reformat_cpp.sh 将根据项目偏好重新格式化C++代码。

如果你正在写一本新的 .cpp -它应该被添加到重新格式化脚本的列表中。

cppcheck静态分析仪

你可以在本地运行 scripts/cppcheck.sh 这是cppcheck实用程序的包装器脚本。此工具用作代码质量控制的一部分。

cppcheck可能有误报。一般来说,最好对代码进行一点修改,使其更“明显”,并避免那些误报。如果不可能,可以在代码中添加注释,如

/* cppcheck-suppress duplicateBreak */

在前一行。用cppcheck发出的违反规则的实际名称替换duplicateBreak。

Cang Static Analyzer(CSA)

CSA由GitHub操作工作流运行。您也可以在本地运行它。

初步步骤:安装clang。例如:

wget https://releases.llvm.org/9.0.0/clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
tar xJf clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
mv clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04 clang+llvm-9
export PATH=$PWD/clang+llvm-9/bin:$PATH

使用配置项目 scan-build 叮当声的效用:

::

Mkdir CSA_BUILD CD CSA_BUILD扫描-BUILD cmake..

使用以下工具构建 scan-build

scan-build make [-j8]

如果CSA发现错误,它们将在构建过程中发出。在这种情况下,在构建过程结束时, scan-build 将发出一条警告消息,指示已找到错误以及如何显示错误报告。这是一种类似于

scan-view /tmp/scan-build-2021-03-15-121416-17476-1

这将打开带有交互式报告的web浏览器。

CSA也可能有假阳性。一般来说,当代码非常琐碎/做出了难以一目了然检查的假设时,就会发生这种情况。您将需要添加额外的检查或返工一点,使它更“明显”的CSA。这也将有助于人类阅读你的代码!

打字错误检测和修复

scripts/fix_typos.sh

包括你使用的(IWYU)

管理C是一件痛苦的事。IWYU使得更新头文件更容易一些。IWYU扫描被调用函数的代码,并确保所有这些函数的头都存在并且按顺序排序。但是,不能盲目地将IWYU应用于项目。它不了解ifdefs、其他平台或项目内部标题的订单要求。因此,使用它的方法是在源代码的副本上运行它,并只合并有意义的更改。添加的标准头应该总是可以安全地合并的。其余的需要仔细评估。有关动机和详细信息,请参阅IWYU文档。

IWYU docs