PX4 Guide (main)

中文 (Chinese)

English

中文 (Chinese)

English

Appearance

GIT 示例 ​

为 PX4 贡献代码 ​

为 PX4 添加功能需要遵循既定的工作流程。为了在 PX4 上分享您的贡献，您可以参考以下示例。

  • 若您还未在 GitHub 注册，请前往 注册。

  • 复刻（Fork）PX4 - Autopilot 仓库（具体操作见 此处）。

  • 将复刻的分支克隆到本地计算机：

    sh
    cd ~/wherever/
git clone https://github.com/<your git name>/PX4-Autopilot.git

  • 进入新目录，初始化并更新子模块，同时添加原始的上游固件仓库：

    sh
    cd PX4-Autopilot
git submodule update --init --recursive
git remote add upstream https://github.com/PX4/PX4-Autopilot.git

  • 此时，您应该有两个远程仓库：一个名为 upstream，指向 PX4/PX4 - Autopilot；另一个名为 origin，指向您复刻的 PX4 仓库。

  • 可以通过以下命令进行检查：

    sh
    git remote -v

  • 对当前的主分支进行您想要添加的更改。

  • 使用能代表您功能的有意义的名称创建一个新分支：

    sh
    git checkout -b <your feature branch name>

    您可以使用 git branch 命令确保您处于正确的分支上。

  • 通过添加相应的文件，将您希望包含在提交中的更改添加进来：

    sh
    git add <file name>

    如果您更喜欢使用图形界面来添加文件，可以参考 Gitk 或 git add -p。

  • 提交添加的文件，并附上一条有意义的消息来解释您的更改：

    sh
    git commit -m "<your commit message>"

    关于良好的提交消息规范，请参考 源代码管理 部分。

  • 可能一段时间过去了，上游主分支 已经发生了变化。PX4 倾向于使用线性提交历史，并采用 git rebase。为了将上游的最新更改包含到您的本地分支中，先切换到您的主分支：

    sh
    git checkout main

    然后从上游主分支拉取最新的提交：

    sh
    git pull upstream main

    现在您的本地主分支已经是最新状态了。切换回您的功能分支，并基于更新后的主分支进行变基操作：

    sh
    git checkout <your feature branch name>
git rebase main

  • 现在，您可以将本地提交推送到您复刻的仓库分支：

    sh
    git push origin <your feature branch name>

  • 您可以通过在浏览器中访问您复刻的仓库 https://github.com/<your git name>/PX4-Autopilot.git 来验证推送是否成功。在那里，您应该会看到一条消息，表明一个新分支已被推送到您复刻的仓库。

  • 现在是时候创建一个拉取请求（PR）了。在“新分支消息”的右侧（参考上一步），您应该会看到一个绿色按钮，上面写着“Compare & Create Pull Request”。然后，它会列出您的更改，您必须添加一个有意义的标题（在提交 PR 的情况下，通常就是提交消息）和消息（解释您进行这些更改的原因，可参考 其他拉取请求）。

  • 大功告成！PX4 的相关负责人将查看您的贡献，并决定是否将其集成。请不时查看他们是否对您的更改有疑问。

切换源代码树 ​

我们建议使用 PX4 的 make 命令在源代码分支之间进行切换。这样可以避免您记住更新子模块和清理构建产物的命令（切换后未移除的构建文件会导致“未跟踪文件”错误）。

要在分支之间进行切换：

  1. 清理当前分支，取消初始化子模块并移除所有构建产物：

    sh
    make clean
make distclean

  2. 切换到一个新的分支或标签（这里我们首先从 upstream 远程仓库获取虚构的分支 “PR_test_branch”）：

    sh
    git fetch upstream PR_test_branch
git checkout PR_test_branch

  3. 获取新分支的子模块：

    sh
    make submodulesclean

获取特定版本代码 ​

特定的 PX4 版本以 发布分支 的标签形式存在，命名格式为 v<release>。这些标签 在 Github 上列出（或者您可以使用 git tag -l 查询所有标签）。

要获取 特定旧版本（标签）的源代码：

  1. 克隆 PX4 - Autopilot 仓库并进入 PX4 - Autopilot 目录：

    sh
    git clone https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot

    :::note 您可以复用现有的仓库，而不是克隆一个新的。在这种情况下，清理构建环境（见 切换源代码树）：

    sh
    make clean
make distclean

    :::

  2. 检出特定标签的代码（例如，对于标签 v1.13.0 - beta2）：

    sh
    git checkout v1.13.0-beta2

  3. 更新子模块：

    sh
    make submodulesclean

获取发布分支 ​

发布分支从 main 分支派生而来，用于将 main 分支中必要的更改反向移植到某个版本中。这些分支的命名格式为 release/<release_number>（例如 release/v1.13）。这些分支 在此列出。

要获取一个发布分支：

  • 克隆 PX4 - Autopilot 仓库并进入 PX4 - Autopilot 目录：

    sh
    git clone https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot

    :::note 您可以复用现有的仓库，而不是克隆一个新的。在这种情况下，清理构建环境（见 切换源代码树）：

    sh
    make clean
make distclean

    :::

  • 获取所需的发布分支。例如，假设您想要 PX4 v1.14 的源代码：

    sh
    git fetch origin release/1.14

  • 检出该分支的代码：

    sh
    git checkout release/1.14

  • 更新子模块：

    sh
    make submodulesclean

更新子模块 ​

有几种方法可以更新子模块。您可以克隆仓库，或者进入子模块目录，然后遵循与 为 PX4 贡献代码 相同的步骤。

为子模块更新提交 PR ​

在您为子模块 X 仓库提交了一个 PR，并且 bug 修复/功能添加已经包含在子模块 X 的当前主分支中之后，就需要进行这一步。由于固件仍然指向您更新之前的一个提交，因此需要提交一个子模块拉取请求，以便固件使用的子模块指向最新的提交。

sh
cd Firmware

  • 创建一个分支，描述子模块更新的 bug 修复/功能：

    sh
    git checkout -b pr-some-fix

  • 进入子模块的子目录：

    sh
    cd <path to submodule>

  • PX4 子模块可能不一定指向最新的提交。因此，首先检出 main 分支并拉取最新的上游代码：

    sh
    git checkout main
git pull upstream main

  • 回到固件目录，像往常一样添加、提交并推送更改：

    sh
    cd -
git add <path to submodule>
git commit -m "Update submodule to include ..."
git push upstream pr-some-fix

查看拉取请求 ​

即使要合并的分支只存在于某人的复刻仓库中，您也可以测试他人的拉取请求（更改尚未合并）。执行以下指令：

sh
git fetch upstream  pull/<PR ID>/head:<branch name>

PR ID 是拉取请求标题旁边的数字（不带 #），<branch name> 也可以在 PR ID 下方找到，例如 <the other persons git name>:<branch name>。之后，您可以查看本地新创建的分支：

sh
git branch

然后切换到那个分支：

sh
git checkout <branch name>

常见错误 ​

强制推送到复刻仓库 ​

在提交第一个 PR 后，PX4 社区的人员会审查您的更改。在大多数情况下，这意味着您必须根据评审意见修复本地分支。在本地更改文件后，功能分支需要再次基于最新的上游 main 分支进行变基操作。但是，变基之后，将功能分支直接推送到复刻仓库就不再可行，而是需要使用强制推送：

sh
git push --force-with-lease origin <your feature branch name>

变基时出现合并冲突 ​

如果在 git rebase 过程中出现冲突，请参考 此指南。

拉取时出现合并冲突 ​

如果在 git pull 过程中出现冲突，请参考 此指南。

由于 git 标签过时导致的构建错误 ​

如果 git 标签过时，会出现构建错误 Error: PX4 version too low, expected at least vx.x.x。

可以通过获取上游仓库的标签来解决这个问题：

sh
git fetch upstream --tags