# 源代码管理

# 分支模型

PX4 项目使用三分支 Git 模型:

我们试着 通过重置保留线性历史 (opens new window),并且避免 Github flow (opens new window)。 然而,由于全球团队和快速的发展,我们可能有时会进行合并。

To contribute new functionality, sign up for Github (opens new window), then fork (opens new window) the repository, create a new branch (opens new window), add your changes, and finally send a pull request (opens new window). 更改将在通过我们的 持续整合 (opens new window) 测试时合并。

所有代码贡献都必须在许可的 BSD 3 条款的许可证 (opens new window) 下进行,不得对其使用施加任何进一步的限制。

# Code Style

PX4 uses the Google C++ style guide (opens new window), with the following (minimal) modifications:

# Tabs

  • Tabs are used for indentation (equivalent to 8 spaces).
  • Spaces are used for alignment.

# Line Length

  • Maximum line length is 120 characters.

# File Extensions

  • Source files use extension *.cpp instead of *.cc.

# Function and Method Names

  • lowerCamelCase() is used for functions and methods to visually distinguish them from ClassConstructors() and ClassNames.

# Class Privacy Keywords

  • zero spaces before public:, private:, or protected: keywords.

# Example Code Snippet

class MyClass {
public:

        /**
         * @brief Description of what this function does.
         *
         * @param[in] input_param Clear description of the input [units]
         * @return Whatever we are returning [units]
         */
        float doSomething(const float input_param) const {
                const float in_scope_variable = input_param + kConstantFloat;
                return in_scope_variable * private_member_variable_;
        }

        void setPrivateMember(const float private_member_variable) { private_member_variable_ = private_member_variable; }

        /**
         * @return Whatever we are "getting" [units]
         */
        float getPrivateMember() const { return private_member_variable_; }

private:

        // Clear description of the constant if not completely obvious from the name [units]
        static constexpr float kConstantFloat = ...;  

        // Clear description of the variable if not completely obvious from the name [units]
        float private_member_variable_{...};
};

# 提交和提交消息

PX4 developers are encouraged to create appropriate in-source documentation.

注解

Source-code documentation standards are not enforced, and the code is currently inconsistently documented. We'd like to do better!

Currently we have two types of source-based documentation:

Developers should name C++ entities (classes, functions, variables etc.) such that their purpose can be inferred - reducing the need for explicit documentation. :::

  • Do not add documentation that can trivially be inferred from C++ entity names.
  • ALWAYS specify units of variables, constants, and input/return parameters where they are defined.
  • Commonly you may want to add information about corner cases and error handling.
  • Doxgyen (opens new window) tags should be used if documentation is needed: @class, @file, @param, @return, @brief, @var, @see, @note. A good example of usage is src/modules/events/send_event.h (opens new window).

Please avoid "magic numbers", for example, where does this number in the conditional come from? What about the multiplier on yaw stick input?

if (fabsf(yaw_stick_normalized_input) < 0.1f) {
        yaw_rate_setpoint = 0.0f;
}
else {
        yaw_rate_setpoint = 0.52f * yaw_stick_normalized_input;
}

Instead, define the numbers as named constants with appropriate context in the header:

// Deadzone threshold for normalized yaw stick input
static constexpr float kYawStickDeadzone = 0.1f;

// [rad/s] Deadzone threshold for normalized yaw stick input
static constexpr float kMaxYawRate = math::radians(30.0f);

and update the source implementation.

if (fabsf(yaw_stick_normalized_input) < kYawStickDeadzone) {
        yaw_rate_setpoint = 0.0f;
}
else {
        yaw_rate_setpoint = kMaxYawRate * yaw_stick_normalized_input;
}

# Commits and Commit Messages

Please use descriptive, multi-paragraph commit messages for all non-trivial changes. Structure them well so they make sense in the one-line summary but also provide full detail.

组成部分:在一个句子中解释这一更改。 修复 #1234

将软件组件添加到摘要行的开头,或者通过模块名称或它的描述。
(例如,"mc_att_ctrl" 或 "multicopter 姿态控制器")。

如果问题编号作为<Fixes #1234>添加,Github 将在提交合并到主分支时自动关闭问题。

电文正文可以包含几个段落。
详细描述您的变更。 链接问题和飞行日志或与此项提交的测试结果有关联。

描述这个变化以及你为什么做了修改,而不是只有代码更改内容 (很好: "为低质量GPS 接收的车辆添加额外
安全检查"。
坏: "添加 gps_reception_check() 函数").

已上报:名字 <email@px4.io>

Use git commit -s to sign off on all of your commits. This will add signed-off-by: with your name and email as the last line.

This commit guide is based on best practices for the Linux Kernel and other projects maintained (opens new window) by Linus Torvalds.