fly316/PX4-Autopilot
7
0
Fork 0
mirror of https://gitee.com/mirrors_PX4/PX4-Autopilot.git synced 2026-10-03 15:38:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

Move PX4 Guide source into /docs (#24490)

Browse Source 
* Add vitepress tree

* Update existing workflows so they dont trigger on changes in the docs path

* Add nojekyll, package.json, LICENCE etc

* Add crowdin docs upload/download scripts

* Add docs flaw checker workflows

* Used docs prefix for docs workflows

* Crowdin obvious fixes

* ci: docs move to self hosted runner

runs on a beefy server for faster builds

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: don't run build action for docs or ci changes

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: update runners

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* Add docs/en

* Add docs assets and scripts

* Fix up editlinks to point to PX4 sources

* Download just the translations that are supported

* Add translation sources for zh, uk, ko

* Update latest tranlsation and uorb graphs

* update vitepress to latest

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Hamish Willee
2025-03-13 16:08:27 +11:00
committed by GitHub
co-authored by Ramon Roche
parent 8e6d2ebe4a
commit 88d623bedb
5176 changed files with 558771 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh/contribute/code.md
+196
View File
@@ -0,0 +1,196 @@
# 源代码管理
## 分支模型
PX4 项目使用三分支 Git 模型：
- [main](https://github.com/PX4/PX4-Autopilot/tree/main) is by default unstable and sees rapid development.
- [beta](https://github.com/PX4/PX4-Autopilot/tree/beta) has been thoroughly tested. 它是供飞行测试人员使用的。
- [stable](https://github.com/PX4/PX4-Autopilot/tree/stable) points to the last release.
We try to retain a [linear history through rebases](https://www.atlassian.com/git/tutorials/rewriting-history) and avoid the [Github flow](https://docs.github.com/en/get-started/quickstart/github-flow).
然而，由于全球团队和快速的发展，我们可能有时会进行合并。
To contribute new functionality, [sign up for Github](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account), then [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository, [create a new branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository), add your [changes as commits](#commits-and-commit-messages), and finally [send a pull request](#pull-requests).
Changes will be merged when they pass our [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) tests.
All code contributions have to be under the permissive [BSD 3-clause license](https://opensource.org/licenses/BSD-3-Clause) and all code must not impose any further constraints on the use.
## Code Style
PX4 uses the [Google C++ style guide](https://google.github.io/styleguide/cppguide.html), with the following (minimal) modifications:
::: info
Not all PX4 source code matches the style guide, but any _new code_ that you write should do so — in both new and existing files.
If you update an existing file you are not required to make the whole file comply with the style guide, just the code you've modified.
:::
### 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`.
### Private Class Member Variable Names
- `_underscore_prefixed_snake_case` is used for private class member variable names, as oppose to `underscore_postfixed_`.
### Class Privacy Keywords
- _zero_ spaces before `public:`, `private:`, or `protected:` keywords.
### Example Code Snippet
```cpp
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.
::: info
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:
- `PRINT_MODULE_*` methods are used for both module run time usage instructions and for the [Modules & Commands Reference](../modules/modules_main.md) in this guide.
- The API is documented [in the source code here](https://github.com/PX4/PX4-Autopilot/blob/v1.8.0/src/platforms/px4_module.h#L381).
- Good examples of usage include the [Application/Module Template](../modules/module_template.md) and the files linked from the modules reference.
- We encourage other in-source documentation _where it adds value/is not redundant_.
:::tip
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](http://www.doxygen.nl/) 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](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/events/send_event.h).
Please avoid "magic numbers", for example, where does this number in the conditional come from? What about the multiplier on yaw stick input?
```cpp
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:
```cpp
// 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.
```cpp
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
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.
```plain
Component: Explain the change in one sentence. Fixes #1234
Prepend the software component to the start of the summary
line, either by the module name or a description of it.
(e.g. "mc_att_ctrl" or "multicopter attitude controller").
If the issue number is appended as <Fixes #1234>, Github
will automatically close the issue when the commit is
merged to the master branch.
The body of the message can contain several paragraphs.
Describe in detail what you changed. Link issues and flight
logs either related to this fix or to the testing results
of this commit.
Describe the change and why you changed it, avoid to
paraphrase the code change (Good: "Adds an additional
safety check for vehicles with low quality GPS reception".
Bad: "Add gps_reception_check() function").
Reported-by: Name <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](https://github.com/torvalds/subsurface-for-dirk/blob/a48494d2fbed58c751e9b7e8fbff88582f9b2d02/README#L88-L115) by Linus Torvalds.
## Pull Requests
Github [Pull Requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) are the primary mechanism used to submit new functionality and bug fixes to PX4.
They include the new set of [commits](#commits-and-commit-messages) in your branch (relative the main branch), and a description of the changes.
The description should include:
- An overview of what the changes deliver; enough to understand the broad purpose of the code
- Links to related issues or supporting information.
- Information about what testing of the PR functionality has been done, with links to flight logs.
- Where possible, the results from general [Test Flights](../test_and_ci/test_flights.md) both before and after the change.
docs/zh/contribute/dev_call.md
+39
View File
@@ -0,0 +1,39 @@
# Weekly Community Q&A Call (Previously "Dev Call")
<script setup>
import { useData } from 'vitepress'
const { site } = useData();
</script>
<div v-if="site.title !== 'PX4 Guide (main)'">
<div class="custom-block danger">
<p class="custom-block-title">This page may be out out of date. <a href="https://docs.px4.io/main/en/contribute/dev_call.html">See the latest version</a>.</p>
</div>
</div>
The PX4 dev team and community come together to discuss any topic of interest to the community, ranging from sorting out issues to satisfying your curiosity.
## Who should attend?
- 核心项目维护者
- 组件维护者
- 测试团队负责人
- 无人机编码成员
- Community members (you!)
:::tip
The Community Q&A call is open to all interested community members.
This is a great opportunity to meet the team and contribute to the ongoing development of the platform.
:::
## 讨论什么内容?
We publish a forum post per meeting a week before the call on [PX4 Discuss - weekly-dev-call](https://discuss.px4.io/c/weekly-dev-call) and track the agenda write down the discussion for the day. We welcome any topics that you, as a community member may have questions about / want to discuss!
Please add your topics for discussion to the agenda before the meeting begins, by replying to the meeting note. This will help you formulate your questions more clearly, and allow us to think about them in advance.
## 日程
- TIME: Wednesday 17h00 CET ([subscribe to calendar](https://www.dronecode.org/calendar/))
- **Join the call**: [https://discord.gg/BDYmr6FA6Q](https://discord.gg/BDYmr6FA6Q)
docs/zh/contribute/docs.md
+274
View File
@@ -0,0 +1,274 @@
# 投稿指南
Contributions to the PX4 User Guide are very welcome; from simple fixes to spelling and grammar, through to the creation of whole new sections.
This topic explains how to make and test changes.
Towards the end there is a basic style guide.
:::tip
Note
You will need a (free) [GitHub](https://github.com/) account to contribute to the guides.
:::
## 快速更改
Simple changes to _existing content_ can be made by clicking the **Edit on GitHub** link that appears at the bottom of every page (this opens the page on Github for editing).
![Vitepress: Edit Page button](../../assets/vuepress/vuepress_edit_page_on_github_link.png)
The guide uses the <a href="https://www.gitbook.com/about">Gitbook</a> toolchain. Change requests can be either done on the Gitbook website using the <a href="https://gitbookio.gitbooks.io/documentation/content/editor/index.html">Gitbook editor</a> or locally (more flexible, but less user-friendly).
1. Open the page.
2. Click the **Edit on GitHub** link below the page content.
3. At the bottom of the page you'll be prompted to create a separate branch and then guided to submit a <em x-id="3">pull request</em>.
4. Below the Github page editor you'll be prompted to create a separate branch and then guided to submit a _pull request_.
The documentation team will review the request and either merge it or work with you to update it.
## Adding New Content - Big Changes
More substantial changes, including adding new pages or adding/modifying images, aren't as easy to make (or properly test) on Github.
For these kinds of changes we suggest using the same approach as for _code_:
1. Use the _git_ toolchain to get the documentation source code onto your local computer.
2. Modify the documentation as needed (add, change, delete).
3. _Test_ that it builds properly using Vitepress.
4. In order to contribute many changes to the documentation, it is recommended that you follow these steps to add the changes locally and then create a pull request:
The following explain how to get the source code, build locally (to test), and modify the code.
### What Goes Where?
指南使用 <a href="https://legacy.gitbook.com/">旧版Gitbook 工具链</a>
The instructions below explain how to get git and use it on your local computer.
1. Download git for your computer from [https://git-scm.com/downloads](https://git-scm.com/downloads)
2. [Sign up](https://github.com/join) for Github if you haven't already
3. Create a copy (Fork) of the [PX4 User Guide repo](https://github.com/PX4/PX4-user_guide) on Github ([instructions here](https://docs.github.com/en/get-started/quickstart/fork-a-repo)).
4. Clone (copy) your forked repository to your local computer:
```sh
cd ~/wherever/
git clone https://github.com/<your git name>/PX4-user_guide.git
```
For example, to clone the PX4 userguide fork for a user with Github account "john_citizen":
```sh
git clone https://github.com/john_citizen/PX4-user_guide.git
```
5. Navigate to your local repository:
```sh
cd ~/wherever/PX4-user_guide
```
6. Add a _remote_ called "upstream" to point to the PX4 version of the library:
```sh
git remote add upstream https://github.com/PX4/PX4-user_guide.git
```
:::tip
A "remote" is a handle to a particular repository.
The remote named _origin_ is created by default when you clone the repository, and points to _your fork_ of the guide.
Above you create a new remote _upstream_ that points to the PX4 project version of the documents.
:::
7. Create a branch for your changes:
```sh
git checkout -b <your_feature_branch_name>
```
This creates a local branch on your computer named `your_feature_branch_name`.
8. Make changes to the documentation as needed (general guidance on this in following sections)
9. Once you are satisfied with your changes, you can add them to your local branch using a "commit":
```sh
git add <file name>
git commit -m "<your commit message>"
```
For a good commit message, please refer to the [Source Code Management](../contribute/code.md#commits-and-commit-messages) section.
10. Push your local branch (including commits added to it) to your forked repository on Github.
```sh
git push origin your_feature_branch_name
```
11. Go to your forked repository on Github in a web browser, e.g.: `https://github.com/<your git name>/PX4-user_guide.git`.
There you should see the message that a new branch has been pushed to your forked repository.
12. Create a pull request (PR):
- On the right hand side of the "new branch message" (see one step before), you should see a green button saying "Compare & Create Pull Request".
Press it.
- A pull request template will be created.
It will list your commits and you can (must) add a meaningful title (in case of a one commit PR, it's usually the commit message) and message (<span style="color:orange">explain what you did for what reason</span>.
Check [other pull requests](https://github.com/PX4/PX4-user_guide/pulls) for comparison)
13. You're done!
Maintainers for the PX4 User Guide will now have a look at your contribution and decide if they want to integrate it.
Check if they have questions on your changes every once in a while.
### Gitbook Documentation Toolchain
概述：
1. Install the [Vitepress prerequisites](https://vitepress.dev/guide/getting-started#prerequisites):
- [Nodejs 18+](https://nodejs.org/en)
- [Yarn classic](https://classic.yarnpkg.com/en/docs/install)
2. Navigate to your local repository:
```sh
cd ~/wherever/PX4-user_guide
```
3. Install dependencies (including Vitepress):
```sh
yarn install
```
4. Preview and serve the library:
```sh
yarn start
```
- Once the development/preview server has built the library (less than a minute for the first time) it will show you the URL you can preview the site on.
This will be something like: `http://localhost:5173/px4_user_guide/`.
- Stop serving using **CTRL+C** in the terminal prompt.
5. Open previewed pages in your local editor:
First specify a local text editor file using the `EDITOR` environment variable, before calling `yarn start` to preview the library.
For example, on Windows command line you can enable VSCode as your default editor by entering:
```sh
set EDITOR=code
```
The **Open in your editor** link at the bottom of each page will then open the current page in the editor (this replaces the _Open in GitHub_ link).
6. You can build the library as it would be done for deployment:
```sh
# Ubuntu
yarn docs:build
# Windows
yarn docs:buildwin
```
:::tip
Use `yarn start` to preview changes _as you make them_ (documents are updated and served very quickly).
Before submitting a PR you should also build it using `yarn docs:build`, as this can highlight issues that are not visible when using `yarn start`.
:::
### Source Code Structure
The guide uses the [Vitepress](https://vitepress.dev/) toolchain.
In overview:
- Pages are written in separate files using markdown.
- The syntax is almost the same as that used by the Github wiki.
- Vitepress also supports some [markdown extensions](https://vitepress.dev/guide/markdown#markdown-extensions).
We try and avoid using these, except for [tips, warning, etc.](https://vitepress.dev/guide/markdown#default-title).
This might be revisited - there are some interesting options provided!
- This is a [multilingual](https://vitepress.dev/guide/i18n) book:
- Pages for each language are stored in the folder named for the associated language code (e.g. "en" for English, "zh" for Chinese, "ko" for Korean).
- Only edit the ENGLISH (`/en`) version of files.
We use [Crowdin](../contribute/translation.md) to manage the translations.
- All pages must be in an appropriately named sub-folder of `/en` (e.g. this page is in folder `en/contribute/`).
- This makes linking easier because other pages and images are always as the same relative levels
- The _structure_ of the book is defined in `SUMMARY.md`.
- If you add a new page to the guide you must also add an entry to this file!
:::tip
This is not "standard vitepress" way to define the sidebar (the summary file is imported by [.vitepress/get_sidebar.js](https://github.com/PX4/PX4-user_guide/blob/main/.vitepress/get_sidebar.js)).
:::
- Images must be stored in a sub folder of `/assets`.
This is two folders down from content folders, so if you add an image you will reference it like:
```plain
![Image Description](../../assets/path_to_file/filename.jpg)
```
- A file named **package.json** defines any dependencies of the build.
- A web hook is used to track whenever files are merged into the master branch on this repository, causing the book to rebuild.
### 文档规范指南
When you add a new page you must also add it to `en/SUMMARY.md`!
## 翻译
1. 图片
- Put new markdown files in an appropriate sub-folder of `/en/`, such as `/en/contribute/`.
Do not further nest folders.
- Put new image files in an appropriate nested sub-folder of `/assets/`.
Deeper nesting is allowed/encouraged.
- Use descriptive names for folders and files.
In particular, image filenames should describe what they contain (don't name as "image1.png")
- Use lower case filenames and separate words using underscores (`_`).
2. 内容:
- 将新文件放入相应的子文件夹
- New images should be created in a sub-folder of `/assets/` (so they can be shared between translations).
- SVG files are preferred for diagrams.
PNG files are preferred over JPG for screenshots.
3. Content:
- Use "style" (**bold**, _emphasis_, etc.) consistently and sparingly (as little as possible).
- **Bold** for button presses and menu definitions.
- _Emphasis_ for tool names such as _QGroundControl_ or _prettier_.
- `code` for file paths, and code, parameter names that aren't linked, using tools in a command line, such as `prettier`.
- Headings and page titles should use "First Letter Capitalisation".
- The page title should be a first level heading (`#`).
All other headings should be h2 (`##`) or lower.
- Don't add any style to headings.
- Don't translate the text indicating the name of an `info`, `tip` or `warning` declaration (e.g. `::: tip`) as this precise text is required to render the aside properly.
- Break lines on sentences by preference.
Don't break lines based on some arbitrary line length.
- Format using _prettier_ (_VSCode_ is a has extensions can be used for this).
4. Videos:
- Youtube videos can be added using the format `<lite-youtube videoid="<youtube-video-id>" title="your title"/>` (supported via the [https://www.npmjs.com/package/lite-youtube-embed](https://www.npmjs.com/package/lite-youtube-embed) custom element, which has other parameters you can pass).
- Use instructional videos sparingly as they date badly, and are hard to maintain.
- Cool videos of airframes in flight are always welcome.
## 许可证
Add new files in folders that cover similar topics.
Then reference them in the sidebar (`/en/SUMMARY.md`) in line with the existing structure!
## 翻译
For information about translation see: [Translation](../contribute/translation.md).
## Licence
All PX4/Dronecode documentation is free to use and modify under terms of the permissive [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license.
docs/zh/contribute/git_examples.md
+305
View File
@@ -0,0 +1,305 @@
# GIT 示例
<a id="contributing_code"></a>
## 为 PX4 贡献代码
Adding a feature to PX4 follows a defined workflow. In order to share your contributions on PX4, you can follow this example. 为了在 px4 上分享您的贡献, 您可以遵循此示例。
- [Sign up](https://github.com/join) for github if you haven't already
- Fork the PX4-Autopilot repo (see [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo))
- 将分支克隆到本地计算机
```sh
cd ~/wherever/
git clone https://github.com/<your git name>/PX4-Autopilot.git
```
- Go into the new directory, initialize and update the submodules, and add the original upstream Firmware
```sh
cd PX4-Autopilot
git submodule update --init --recursive
git remote add upstream https://github.com/PX4/PX4-Autopilot.git
```
- You should have now two remote repositories: One repository is called `upstream` that points to PX4/PX4-Autopilot, and one repository `origin` that points to your forked copy of the PX4 repository.
- 这可以通过以下命令进行检查:
```sh
git remote -v
```
- Make the changes that you want to add to the current main.
- 使用代表您的功能的有意义的名称创建一个新分支
```sh
git checkout -b <your feature branch name>
```
you can use the command `git branch` to make sure you're on the right branch.
- 通过添加相应的文件添加您希望成为提交的一部分的更改
```sh
git add <file name>
```
If you prefer having a GUI to add your files see [Gitk](https://git-scm.com/book/en/v2/Git-in-Other-Environments-Graphical-Interfaces) or [`git add -p`](http://nuclearsquid.com/writings/git-add/).
- 提交添加的文件, 并顺便记录一条有意义的消息, 解释您的更改
```sh
git commit -m "<your commit message>"
```
For a good commit message, please refer to the [Source Code Management](../contribute/code.md#commits-and-commit-messages) section.
- Some time might have passed and the [upstream main](https://github.com/PX4/PX4-Autopilot.git) has changed.
PX4 prefers a linear commit history and uses [git rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing).
To include the newest changes from upstream in your local branch, switch to your main branch
```sh
git checkout main
```
Then pull the newest commits from upstream main
```sh
git pull upstream main
```
Now your local main is up to date.
Switch back to your feature branch and rebase on your updated main
```sh
git checkout <your feature branch name>
git rebase main
```
- 现在, 您可以将本地提交推送到分支版本库
```sh
git push origin <your feature branch name>
```
- You can verify that the push was successful by going to your forked repository in your browser: `https://github.com/<your git name>/PX4-Autopilot.git`
There you should see the message that a new branch has been pushed to your forked repository.
- 现在是时候创建一个拉取请求 (PR) 了。
On the right hand side of the "new branch message" (see one step before), you should see a green button saying "Compare & Create Pull Request".
然后, 它应该列出你的更改，你必须添加一个有意义的标题 (在提交 PR 的情况下, 它通常是提交消息) 和消息 (<span style="color:orange">解释你做了这些更改的原因 </span>，
Check [other pull requests](https://github.com/PX4/PX4-Autopilot/pulls) for comparison)
- You're done!
You're done! Responsible members of PX4 will now have a look at your contribution and decide if they want to integrate it. Check if they have questions on your changes every once in a while.
Check if they have questions on your changes every once in a while.
## Changing Source Trees
We recommend using PX4 `make` commands to switch between source code branches.
This saves you having to remember the commands to update submodules and clean up build artifacts (build files that are not removed will result in "untracked files" errors after the switch).
To switch between branches:
1. Clean up the current branch, de-initializing submodule and removing all build artifacts:
```sh
make clean
make distclean
```
2. Switch to a new branch or tag (here we first fetch the fictional branch "PR_test_branch" from the `upstream` remote):
```sh
git fetch upstream PR_test_branch
git checkout PR_test_branch
```
3. Get the submodules for the new branch:
```sh
make submodulesclean
```
<!-- FYI: Cleaning commands in https://github.com/PX4/PX4-Autopilot/blob/main/Makefile#L494 -->
## 更新子模块
Specific PX4 point releases are made as tags of the [release branches](#get-a-release-branch), and are named using the format `v<release>`.
These are [listed on Github here](https://github.com/PX4/PX4-Autopilot/releases?q=release\&expanded=true) (or you can query all tags using `git tag -l`).
To get the source code for a _specific older release_ (tag):
1. Clone the PX4-Autopilot repo and navigate into _PX4-Autopilot_ directory:
```sh
git clone https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot
```
:::note
You can reuse an existing repo rather than cloning a new one.
In this case clean the build environment (see [changing source trees](#changing-source-trees)):
```sh
make clean
make distclean
```
:::
2. Checkout code for particular tag (e.g. for tag v1.13.0-beta2)
```sh
git checkout v1.13.0-beta2
```
3. Update submodules:
```sh
make submodulesclean
```
## Get a Release Branch
Releases branches are branched of `main`, and used to backport necessary changes from main into a release.
The branches are named using the format `release/<release_number>` (e.g. `release/v1.13`).
The are [listed here](https://github.com/PX4/PX4-Autopilot/branches/all?query=release).
To get a release branch:
- Clone the PX4-Autopilot repo and navigate into _PX4-Autopilot_ directory:
```sh
git clone https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot
```
:::note
You can reuse an existing repo rather than cloning a new one.
In this case clean the build environment (see [changing source trees](#changing-source-trees)):
```sh
make clean
make distclean
```
:::
- Fetch the desired release branch.
For example, assuming you want the source for PX4 v1.14:
```sh
git fetch origin release/1.14
```
- Checkout the code for the branch
```sh
git checkout release/1.14
```
- Update submodules:
```sh
make submodulesclean
```
## 更新子模块
有几种方法可以更新子模块。
Either you clone the repository or you go in the submodule directory and follow the same procedure as in [Contributing code to PX4](#contributing_code).
## 为子模块更新执行 PR
This is required after you have done a PR for a submodule X repository and the bug-fix / feature-add is in the current main of submodule X. Since the Firmware still points to a commit before your update, a submodule pull request is required such that the submodule used by the Firmware points to the newest commit.
```sh
cd Firmware
```
- 创建一个分支，描述子模块更新的 bug 修复/功能：
```sh
git checkout -b pr-some-fix
```
- 进入子模块的子目录
```sh
cd <path to submodule>
```
- PX4 submodule might not necessarily point to the newest commit. Therefore, first checkout master and pull the newest upstream code. Therefore, first checkout main and pull the newest upstream code.
```sh
git checkout main
git pull upstream main
```
- 回到 Firmware 目录，如往常一样添加、提交和上推更改。
```sh
cd -
git add <path to submodule>
git commit -m "Update submodule to include ..."
git push upstream pr-some-fix
```
## 查看拉取请求
You can test someone's pull request (changes are not yet merged) even if the branch to merge only exists on the fork from that person. Do the following 执行以下指令：:
```sh
git fetch upstream pull/<PR ID>/head:<branch name>
```
`PR ID` is the number right next to the PR's title (without the #) and the `<branch name>` can also be found right below the `PR ID`, e.g. `<the other persons git name>:<branch name>`. 之后, 您可以看到新创建的分支在本地
```sh
git branch
```
然后切换到那个分支
```sh
git checkout <branch name>
```
## 常见错误
### 强制推送到分叉存储库
做完第一个 PR 后, 来自 PX4 社区的人将回顾你的更改。 在大多数情况下, 这意味着您必须根据评审来修复本地分支。 After changing the files locally, the feature branch needs to be rebased again with the most recent upstream/main. 但是, 在重新建立基础后, 不再可能将特征分支直接推送到分叉存储库, 而是需要使用强制推送:
```sh
git push --force-with-lease origin <your feature branch name>
```
### 重新建立合并冲突
If a conflict occurs during a `git rebase`, please refer to [this guide](https://docs.github.com/en/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase).
### 拉取合并冲突
If a conflict occurs during a `git pull`, please refer to [this guide](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/#competing-line-change-merge-conflicts).
### Build error due to git tags out of date
The build error `Error: PX4 version too low, expected at least vx.x.x` occurs if git tags are out of date.
This can be solved by fetching the upstream repository tags:
```sh
git add -p](http://nuclearsquid.com/writings/git-add/). * Commit the added files with a meaningful message explaining your changes
```
docs/zh/contribute/index.md
+29
View File
@@ -0,0 +1,29 @@
# Community
<script setup>
import { useData } from 'vitepress'
const { site } = useData();
</script>
<div v-if="site.title !== 'PX4 Guide (main)'">
<div class="custom-block danger">
<p class="custom-block-title">This page may be out out of date. <a href="https://docs.px4.io/main/en/contribute/">See the latest version</a>.</p>
</div>
</div>
Welcome to the PX4 Community!
:::tip
We pledge to adhere to the [PX4 code of conduct](https://github.com/PX4/PX4-Autopilot/blob/main/CODE_OF_CONDUCT.md), which aims to foster an open and welcoming environment.
:::
This section contains information about how you can meet with the community and contribute to PX4:
- [Dev Call](../contribute/dev_call.md) - Discuss architecture, pull requests, impacting issues with the dev team
- [Maintainers](./maintainers.md) - Maintainers of PX4 Subsystems and Ecosystem
- [Support](../contribute/support.md) - Get help and raise issues
- [Source Code Management](../contribute/code.md) - Work with PX4 code
- [Documentation](../contribute/docs.md) - Improve the docs
- [Translation](../contribute/translation.md) - Translate using Crowdin
- [Terminology/Notation](../contribute/notation.md) - Terms and symbols used in the docs
- [Licenses](../contribute/licenses.md) - PX4 and Pixhawk licensing
docs/zh/contribute/licenses.md
+12
View File
@@ -0,0 +1,12 @@
# 许可证
:::info
All code contributions must be made under the permissive [BSD 3-clause license](https://opensource.org/licenses/BSD-3-Clause) and must not impose any further constraints on its use.
:::
This page documents the licenses of various components in the system.
- [PX4 Flight Stack](https://github.com/PX4/PX4-Autopilot) &mdash; BSD
- [PX4 Middleware](https://github.com/PX4/PX4-Autopilot) &mdash; BSD
- [Pixhawk Hardware](https://github.com/PX4/Hardware) &mdash; CC-BY-SA 3.0
- [PX4 User Guide](https://github.com/PX4/PX4-user_guide) (Documentation) &mdash; [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
docs/zh/contribute/maintainers.md
+76
View File
@@ -0,0 +1,76 @@
# Maintainer Role
Dronecode maintainers have technical leadership and responsibility for specific areas of PX4, and for other ecosystem components such as MAVLink, MAVSDK, QGroundControl, and others.
The maintainer role is defined by the community with help and supervision from the [Dronecode Foundation](https://www.dronecode.org/).
To find the most up-to-date maintainers list, visit [PX4-Autopilot README](https://github.com/PX4/PX4-Autopilot#maintenance-team).
## Recruitment Process
If you would like to join the PX4 maintainers team or if you want to nominate someone else follow the steps below:
1. Read the [role description](#dronecode-maintainer-role-description), and make sure you understand the responsibilities of the role.
2. To nominate yourself, reach out to one of the maintainers (see the complete list in the [PX4-Autopilot README](https://github.com/PX4/PX4-Autopilot#maintenance-team)), and seek their sponsorship.
3. Express your interest in becoming a maintainer, and specify which area you would like to maintain.
4. The sponsoring maintainer needs to bring this up for discussion in one of the [weekly developer calls](dev_call.md).
The maintainer team will vote on the call to determine whether to accept you as a maintainer.
## Onboarding Process
Once accepted every maintainers will go through the following process:
1. **Discord** server admin will grant you the `dev team` role, which gives you:
1. Basic admin privileges on discord.
2. Access to the `#maintainers` channel.
2. You will be given access to the GitHub team: "[`Dev Team`](https://github.com/orgs/PX4/teams/dev-team)" which grants you:
1. Permission to merge the PR of any of PX4 workspace repositories after it's approved
2. Permission to trigger GitHub actions when a new contributor opens a PR.
3. Permission to edit Issue/PR contents.
3. **Add your info to official PX4 channels**:
1. Include your information on the PX4 [README](https://github.com/PX4/PX4-Autopilot/blob/main/README.md) next to the rest of the team
2. Listed on the [Maintainers section](https://px4.io/community/maintainers/) of the PX4 website.
3. Add your information to the internal Dronecode database of maintainers to keep you in sync.
4. Community introduction to the new maintainer in the form of a forum post, which is promoted through ever growing official channels
## Dronecode Maintainer Role Description
### 概要
Maintainers lead/manage the development of a **specific category (referred to as category below)** of any Open Source Projects hosted within the Dronecode Foundation, such as the PX4 Autopilot.
### Responsibilities
1. Take charge of overseeing the development in their category.
2. Provide guidance/advice on community members in their category.
3. Review relevant pull requests and issues from the community on GitHub.
4. Coordinate with the maintainer group.
5. Keep regular attendance on [weekly meetings ](dev_call.md).
6. Help create and maintain a roadmap for the project your represent.
7. Uphold the [Code of Conduct](https://github.com/Dronecode/foundation/blob/main/CODE-OF-CONDUCT.md) of our community.
### Qualifications
1. Proven track record of valuable contributions.
2. Domain expertise in the category field.
3. Good overview of the project you are applying to.
4. You need to manage approval from your employer when relevant.
### Perks
1. **Official recognition** as the maintainer in Dronecode/PX4 website, documentation, community and social media.
2. **Github & Discord privileges** (described in the [onboarding process](#onboarding-process)).
3. Priority placement to the yearly **PX4 Developer Summit** scholarship which helps you with travel reimbursement.
### Tools we Provide to Assist You
Dronecode will provide the following tools to help you:
1. **Community survey**: If you need any insight into the community's opinion, we will send out social media posts, mailing lists, announcements in Discord server to get that answer for you.
2. **Workflow automation**: We will provide workflow for PR/Issue review & tagging process to help you.
And as always, don't hesitate to reach out if you need help with anything.
We are here for you!
### Point of Contact
Regarding questions about the maintainer role, please contact the maintainer team.
docs/zh/contribute/notation.md
+98
View File
@@ -0,0 +1,98 @@
# 术语
本指南中的文本和图表中使用了以下术语、符号和装饰器。
## 符号
- Bold face variables indicate vectors or matrices and non-bold face variables represent scalars.
- The default frame for each variable is the local frame: $\ell{}$.
Right [superscripts](#superscripts) represent the coordinate frame.
If no right superscript is present, then the default frame $\ell{}$ is assumed.
An exception is given by Rotation Matrices, where the lower right subscripts indicates the current frame and the right superscripts the target frame.
- Variables and subscripts can share the same letter, but they always have different meaning.
## Acronyms
| Acronym | Expansion |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AOA | Angle Of Attack. Also named _alpha_. |
| AOS | Angle Of Sideslip. Also named _beta_. |
| FRD | Coordinate system where the X-axis is pointing towards the Front of the vehicle, the Y-axis is pointing Right and the Z-axis is pointing Down, completing the right-hand rule. |
| FW | Fixed-wing (planes). |
| MC | MultiCopter. |
| MPC 或 MCPC | MultiCopter Position Controller. MultiCopter Position Controller. MPC is also used for Model Predictive Control. |
| NED | Coordinate system where the X-axis is pointing towards the true North, the Y-axis is pointing East and the Z-axis is pointing Down, completing the right-hand rule. |
| PID | Controller with Proportional, Integral and Derivative actions. |
## Symbols
| Variable | 描述 |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| $x,y,z$ | Translation along coordinate axis x,y and z respectively. |
| $\boldsymbol{\mathrm{r}}$ | Position vector: $\boldsymbol{\mathrm{r}} = [x \quad y \quad z]^{T}$ |
| $\boldsymbol{\mathrm{v}}$ | Velocity vector: $\boldsymbol{\mathrm{v}} = \boldsymbol{\mathrm{\dot{r}}}$ |
| $\boldsymbol{\mathrm{a}}$ | Acceleration vector: $\boldsymbol{\mathrm{a}} = \boldsymbol{\mathrm{\dot{v}}} = \boldsymbol{\mathrm{\ddot{r}}}$ |
| $\alpha$ | Angle of attack (AOA). |
| $b$ | Wing span (from tip to tip). |
| $S$ | Wing area. |
| $AR$ | Aspect ratio: $AR = b^2/S$ |
| $\beta$ | Angle of sideslip (AOS). |
| $c$ | Wing chord length. |
| $\delta$ | Aerodynamic control surface angular deflection. A positive deflection generates a negative moment. A positive deflection generates a negative moment. |
| $\phi,\theta,\psi$ | Euler angles roll (=Bank), pitch and yaw (=Heading). |
| $\Psi$ | Attitude vector: $\Psi = [\phi \quad \theta \quad \psi]^T$ |
| $X,Y,Z$ | Forces along coordinate axis x,y and z. |
| $\boldsymbol{\mathrm{F}}$ | Force vector: $\boldsymbol{\mathrm{F}}= [X \quad Y \quad Z]^T$ |
| $D$ | Drag force. |
| $C$ | Cross-wind force. |
| $L$ | Lift force. |
| $g$ | Gravity. |
| $l,m,n$ | Moments around coordinate axis x,y and z. |
| $\boldsymbol{\mathrm{M}}$ | Moment vector $\boldsymbol{\mathrm{M}} = [l \quad m \quad n]^T$ |
| $M$ | Mach number. Can be neglected for scale aircraft. |
| $\boldsymbol{\mathrm{q}}$ | Vector part of Quaternion. |
| $\boldsymbol{\mathrm{\tilde{q}}}$ | Hamiltonian attitude quaternion (see `1` below) |
| $\boldsymbol{\mathrm{R}}_\ell^b$ | Rotation matrix. Rotates a vector from frame $\ell{}$ to frame $b{}$. $\boldsymbol{\mathrm{v}}^b = \boldsymbol{\mathrm{R}}_\ell^b \boldsymbol{\mathrm{v}}^\ell$ |
| $\Lambda$ | Leading-edge sweep angle. |
| $\lambda$ | Aspect ratio. $$AR = b^2/S$$. |
| $w$ | Wind velocity. |
| $p,q,r$ | Angular rates around body axis x,y and z. |
| $\boldsymbol{\omega}^b$ | Attitude vector. $$\Psi = [\phi \quad \theta \quad \psi]^T$$. |
| $\boldsymbol{\mathrm{x}}$ | General state vector. |
- `1` Hamiltonian attitude quaternion. Hamiltonian attitude quaternion. $$\boldsymbol{\mathrm{\tilde{q}}} = (q_0, q_1, q_2, q_3) = (q_0, \boldsymbol{\mathrm{q}})$$. To represent a vector in local frame given a vector in body frame, the following operation can be used: $\boldsymbol{\mathrm{\tilde{v}}}^\ell = \boldsymbol{\mathrm{\tilde{q}}} \, \boldsymbol{\mathrm{\tilde{v}}}^b \, \boldsymbol{\mathrm{\tilde{q}}}^_{}$ (or $\boldsymbol{\mathrm{\tilde{q}}}^{-1}{}$ instead of $\boldsymbol{\mathrm{\tilde{q}}}^_{}$ if $\boldsymbol{\mathrm{\tilde{q}}}{}$ is not unitary). $\boldsymbol{\mathrm{\tilde{v}}}{}$ represents a _quaternionized_ vector: $\boldsymbol{\mathrm{\tilde{v}}} = (0,\boldsymbol{\mathrm{v}})$
### Subscripts / Indices
| Subscripts / Indices | 描述 |
| -------------------- | -------------------------------------------------------------------------------- |
| $a$ | Aileron. |
| $e$ | Elevator. |
| $r$ | Rudder. |
| $Aero$ | Aerodynamic. |
| $T$ | Thrust force. |
| $w$ | Relative airspeed. |
| $x,y,z$ | Component of vector along coordinate axis x, y and z. |
| $N,E,D$ | Component of vector along global north, east and down direction. |
<a id="superscripts"></a>
### Superscripts / Indices
| Superscripts / Indices | 描述 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| $\ell$ | Local-frame. Local-frame. Default for PX4 related variables. |
| $b$ | Body-frame. |
| $w$ | Wind-frame. |
## Decorators
| Decorator | 描述 |
| ------------------------------- | ---------------------------------- |
| $()^\*$ | Complex conjugate. |
| $\dot{()}$ | Time derivative. |
| $\hat{()}$ | Estimate. |
| $\bar{()}$ | Mean. |
| $()^{-1}$ | Matrix inverse. |
| $()^T$ | Matrix transpose. |
| $\tilde{()}$ | Quaternion. |
docs/zh/contribute/support.md
+49
View File
@@ -0,0 +1,49 @@
# 技术支持
<script setup>
import { useData } from 'vitepress'
const { site } = useData();
</script>
<div v-if="site.title !== 'PX4 Guide (main)'">
<div class="custom-block danger">
<p class="custom-block-title">This page may be out out of date. <a href="https://docs.px4.io/main/en/contribute/support.html">See the latest version</a>.</p>
</div>
</div>
This section shows how you can get help from the core dev team and the wider community.
## 论坛和聊天
The core development team and community are active on the following channels:
- [PX4 Discuss Forum](https://discuss.px4.io/) - Post here first!
- [PX4 Discord](https://discord.gg/dronecode) - Post here if you don't get a response in discuss within a few days (include a link to your forum topic).
:::tip
The Discuss Forum is much preferred because it is indexed by search engines and serves as a common knowledge base.
:::
## Diagnosing Problems
在议程中，为重大影响的回拉请求，给与回答。
- Upload logs to [Flight Log Review](https://logs.px4.io/)
- Open a discussion on [PX4 Discuss](https://discuss.px4.io/c/flight-testing/) with a flight report and links to logs.
- The dev team may prompt you to [raise an issue](#issue-bug-reporting) if the problem is caused by a bug.
## Issue & Bug Reporting
- Upload logs to [Flight Log Review](https://logs.px4.io/)
- [Open a Github Issue](https://github.com/PX4/PX4-Autopilot/issues).
This must include a flight report with as much detail as possible (enough for the issue to be reproduced) and links to your logs on Flight review.
## 每周开发通讯
:::tip
Developers are most welcome to attend the [weekly dev call](../contribute/dev_call.md) (and other [developer events](../index.md#calendar-events)) to engage more deeply with the project.
:::
The [Dev Call](../contribute/dev_call.md) is a weekly meeting attended by the PX4 dev team to discuss platform technical details, coordinate activities and perform in-depth analysis.
There is also space in the agenda to discuss pull requests, major impacting issues and Q&A.
docs/zh/contribute/translation.md
+72
View File
@@ -0,0 +1,72 @@
# 翻译
We'd love your help to translate _QGroundControl_, PX4 Metadata (in QGC), and our guides for PX4, _QGroundControl_ and MAVLink!
Our docs (and _QGroundControl_) use the [Crowdin](https://crowdin.com) online tool for translation.
Crowdin automatically imports source topics from Github and presents new and changed strings for translation and/or review (approval).
Crowdin exports the translated documents back out to Github as a "Pull Request" (which the development team periodically review and accept). The exported output contains the source document with any translated and approved text replaced with translated strings (i.e. if a string is not translated/is changed, then it will be displayed in English).
The exported output contains the source document with any translated and approved text replaced with translated strings (i.e. if a string is not translated/is changed, then it will be displayed in English).
:::tip
You will need a (free) [Crowdin account](https://crowdin.com/join) account to join the translation team!
:::
:::info
The benefit of this system is that the translation closely tracks the source documents.
Readers will not be mislead by old and out of date translations.
:::
## 入门指南
The steps to join our translation tream are:
1. Join Crowdin: [https://crowdin.com/join](https://crowdin.com/join)
2. 打开要加入的翻译项目：
- [QGroundControl](https://crowdin.com/project/qgroundcontrol) — QGroundControl UI and hard coded strings.
- [PX4-Metadata-Translations](https://crowdin.com/project/px4-metadata-translations) — PX4 parameter and event descriptions in QGroundControl.
- [PX4 User Guide](https://crowdin.com/project/px4-user-guide)
- [QGroundControl Developer Guide](https://crowdin.com/project/qgroundcontrol-developer-guide)
- [QGroundControl User Guide](https://crowdin.com/project/qgroundcontrol-user-guide)
- [MAVLink Guide](https://crowdin.com/project/mavlink)
3. Select the language you want to translate
4. Click the **Join** button (next to the text _You must join the translators team to be able to participate in this project_)
::: info
You will be notified once your application to join is accepted.
:::
5. Start translating!
## 特别注意事项
### 不要修改句首的 Note, Tip, Warning 字样
Vuepress uses `:::` to mark the beginning of notes, tips and warning:
```html
:::tip
The text for the tip.
:::
```
The text for `:::tip` or `:::warning` etc. should not be modified as it defines the colour of the notebox.
## 添加新语言
If the language you want to translate is not available then you will need to request it by contacting the project owner (there is a contact link on each project's home page).
:::warning
Maintaining a translation is hard!
Before you ask us to create a new language, please find a few other people to help you translate!
:::
## 获取帮助
The _Crowdin_ interface is self explanatory, but there is plenty of additional information on the [knowledgeable](https://support.crowdin.com/).
You can also ask for help from translators and developers in the Dronecode community using [our support channels](../contribute/support.md).