完善了帮助文档中"贡献代码"相关章节

Signed-off-by: latercomer <[email protected]>
nextpilot · Sep 26, 2024 · 64ca12b · 64ca12b
1 parent 4126570
commit 64ca12b
Show file tree

Hide file tree

Showing 19 changed files with 239 additions and 123 deletions.
diff --git a/docs/develop/13.代码贡献/README.md b/docs/develop/13.代码贡献/README.md
diff --git a/docs/develop/13.代码贡献/code-style.md b/docs/develop/13.代码贡献/code-style.md
diff --git a/docs/develop/13.社区支持/README.md b/docs/develop/13.社区支持/README.md
@@ -0,0 +1,9 @@
+# 社区支持
+
+欢迎来到 NextPilot 开发社区！为了营造一个开放和受欢迎的开发环境，我们承诺严格遵守[NextPilot 代码准测](https://github.com/nextpilot/nextpilot-flight-control/blob/main/.github/CODE_OF_CONDUCT.md)。
+
+- [技术支持](./support.md)，获取帮助，故障排查，扫码加群等
+- [贡献代码](./contribute.md)，包括 [代码风格]()、[提交规范]() 等
+- [完善文档]()，完善帮助文档，比如用户手册、开发指南等
+- [语言翻译]()
+- [开源协议]()，NextPilot 项目基于 [BSD 3-clause license](https://opensource.org/licenses/BSD-3-Clause) 开源协议
diff --git a/docs/develop/13.社区支持/contribute.md b/docs/develop/13.社区支持/contribute.md
@@ -0,0 +1,155 @@
+# 贡献代码
+
+本章节需要您具备 git 和 github 的基本知识，会使用 git 版本管理工具，以及熟悉 github 的协作开发流程。
+
+## 分支模型
+
+![](./image/github-flow.png)
+
+NextPilot 依托 Github Flow 进行项目迭代，它只有一个长期分支，就是 master，因此用起来非常简单。
+
+第一步：根据需求，从master拉出新分支，不区分功能分支或补丁分支。
+
+第二步：新分支开发完成后，或者需要讨论的时候，就向master发起一个pull request（简称PR）。
+
+第三步：Pull Request既是一个通知，让别人注意到你的请求，又是一种对话机制，大家一起评审和讨论你的代码。对话过程中，你还可以不断提交代码。
+
+第四步：你的Pull Request被接受，合并进master，重新部署后，原来你拉出来的那个分支就被删除。
+
+## 代码风格
+
+`nextpilot-flight-control.code-workspace` 是 Vscode 工作空间文件，已经配置好以下格式化工具，在 **保存** 文件时会自动触发自动格式化：
+
+- 使用 `clang-format` 对 C/C++ 代码格式化
+- 使用 `black` 对 python 代码格式化
+- 使用 `DavidAnson.vscode-markdownlint` 对 markdown 格式化
+- 使用 `tamasfe.even-better-toml` 对 toml 格式化
+- 使用 `redhat.vscode-yaml` 对 yaml 格式化
+
+### C/C++
+
+NextPilot 使用 [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) 对 C/C++ 代码进行格式化，仓库根目录的 [.clang-format](../.clang-format) 文件定义了格式化的全局配置，相关意义[请参考这里](https://clang.llvm.org/docs/ClangFormatStyleOptions.html)。
+
+如果您 **不希望** 对某个文件下的代码进行格式化，请在该文件夹下添加一个`.clang-format`文件，内容如下：
+
+```yml
+# Available style options are described in https://clang.llvm.org/docs/ClangFormatStyleOptions.html
+#
+# An easy way to create the .clang-format file is:
+#
+# clang-format -style=llvm -dump-config > .clang-format
+#
+---
+Language: Cpp
+DisableFormat: true
+---
+```
+
+核心语句就是 `DisableFormat: true`，表示禁用 clang-format 格式化。
+
+### Python
+
+使用 black 进行自动格式化。
+
+## 提交规范
+
+当我们使用Git提交代码时，都需要填写 `Commit Message` 提交说明。一份清晰简介规范的 `Commit Message` 能让后续代码审查、信息查找、版本回退都更加高效可靠，因此有必要约束开发者编写符合规范的提交说明。
+
+NextPilot 提交信息规范，遵循[Angular Team Commit Specification,](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)，主要包含以下内容：
+
+- type（必填），提交的类别，比如feat，fix等
+- scope（可选），提交的影响范围
+- subject（必填），提交的主题，一般50字内
+- body（可选），提交内容详细说明
+- footer（可选），提交针对某个 issue 或者 task 的链接
+- sign off（必须），所谓Sign-Off就是在`commit message`尾部增加一个作者的信息
+
+```
+<type>(<scope>): <subject>
+
+<body> 提交内容详细说明
+
+<footer> 对应issue或task的链接
+
+<sign-off> 签名
+```
+
+以下是一个标准的 Commit Message：
+
+```
+Commit: 37515b80fa150e1ef315824e63098231d4af4031
+Parents: eb15ff286ba204ebf1eb6b79915a8a9b806cf869
+Author: latercomer <[email protected]>
+Committer: latercomer <[email protected]>
+Date: Thu Sep 26 2024 15:42:49 GMT+0800 (中国标准时间)
+
+✨feat(mc_att_control): add hover thrust throttle estimator
+
+add hover thrust throttle estimator to mc_att_control, set param MC_HOVER_THROTTL_METHOD select estimator method
+
+https://github.com/nextpilot/nextpilot-flight-control/issues/110
+
+Signed-off-by: latercomer <[email protected]>
+```
+
+### 设置Sign-Off
+
+使用命令行`git commit`提交修改时，`-s`选项，可以`commit message`尾部自动添加`Sign-Off`信息：
+
+```shell
+git commit -m "your commit message" -s
+```
+
+VS Code 使用快捷键 `ctr + ,`打开设置页面，搜索`sign off`，然后勾选`Allways Sign Off`
+
+![](./image/vscode-git-sign-off.png)
+
+### 辅助插件
+
+在vscode商店中搜索插件 `git-commit-plugin`，点击安装：
+
+![image-20221021163100119](./image/image-20221021163100119.png)
+
+安装完插件后，在vscode侧边栏`源代码管理`页面，点击下图所示图标，启动插件
+
+![image-20221021163428794](./image/image-20221021163428794.png)
+
+选择这次更改的类型 如：🐞fix是修复 bug 然后选择 **Complete** 即完成本次修改（按下键盘上的 **Esc** 键则离开输入）
+
+#### type(必须)
+
+提交类别，允许使用下面的标识：
+
+- 🎉init：项目初始化
+- ✨feat：增加新功能
+- 🐞fix：修复bug，适合于一次提交直接修复问题
+- 📃docs：文档的添加或修改
+- 🌈style：格式的变动（不影响代码运行）
+- 🦄refactor：重构（即不是新增功能，也不是修改bug的代码变动）
+- 🎈perf：优化相关，比如提升性能、体验
+- 🧪test：增加测试
+- 🔧build：构建过程或辅助工具的变动
+
+![image-20221021163614865](./image/image-20221021163614865.png)
+
+#### scope(可选)
+
+scope 用于说明本次提交的影响范围，比如数据层、控制层、视图层等等，视项目不同而不同。
+
+#### subject(必须)
+
+subject是commit的简短描述，不超过50个字符。完成输入后选择**Complete**，再推送到远端：
+
+![image-20221021164334189](./image/image-20221021164334189.png)
+
+#### Body(可选)
+
+Body 部分是对本次 commit 的详细描述，可以分成多行。
+
+#### Footer(可选)
+
+如果当前的 commit 针对某个 issue，那么可以在 Footer 关闭这个 issue。
+
+## 贡献代码
+
+首先您必须有一个 [github](https://github.com) 账号，才能 [nextpilot-flight-control](https://github.com/nextpilot/nextpilot-flight-control) 项目的开发。
diff --git a/docs/develop/13.社区支持/githelper.md b/docs/develop/13.社区支持/githelper.md
@@ -0,0 +1,47 @@
+# GIT操作指南
+
+## 常用操作
+
+在日常开发中，需要经常提交自己的开发代码（无需完成一个模块才提交），特别是在下班前；当需要将自己的分支代码合并到主分支（main）时，需要做变基处理。
+
+### 获取远端信息
+
+首先，需要将远端的分支信息拉取到本地，方法如下：
+
+```
+git fetch
+```
+
+![image-20221021165220086](./image/image-20221021165220086.png)
+
+### 进行变基操作
+
+将本地分支变基到远端的最新main分支，在变基过程中如果有冲突，需要手动解决：
+
+```
+git rebase origin/main
+```
+
+![image-20221022090648166](./image/image-20221022090648166.png)
+
+![image-20221022090821858](./image/image-20221022090821858.png)
+
+### 删除远端分支
+
+由于变基后，本地的开发者分支的时间节点落后于远端分支的时间节点，现在推送本地分支到远端会失败，因此在推送分支前需要删除远端分支。方法如下：
+
+```
+git push origin --delete <你的分支名称>
+```
+
+![image-20221021165903669](./image/image-20221021165903669.png)
+
+### 提交到远端
+
+变基并删除远端分支之后，就可以将本地分支推动到远端了：
+
+```
+git push
+```
+
+![image-20221021170033561](./image/image-20221021170033561.png)
diff --git a/docs/develop/13.社区支持/image/github-flow.png b/docs/develop/13.社区支持/image/github-flow.png
diff --git a/...13.代码贡献/image/image-20221021163100119.png → ...13.社区支持/image/image-20221021163100119.png b/...13.代码贡献/image/image-20221021163100119.png → ...13.社区支持/image/image-20221021163100119.png
diff --git a/...13.代码贡献/image/image-20221021163428794.png → ...13.社区支持/image/image-20221021163428794.png b/...13.代码贡献/image/image-20221021163428794.png → ...13.社区支持/image/image-20221021163428794.png
diff --git a/...13.代码贡献/image/image-20221021163614865.png → ...13.社区支持/image/image-20221021163614865.png b/...13.代码贡献/image/image-20221021163614865.png → ...13.社区支持/image/image-20221021163614865.png
diff --git a/...13.代码贡献/image/image-20221021164334189.png → ...13.社区支持/image/image-20221021164334189.png b/...13.代码贡献/image/image-20221021164334189.png → ...13.社区支持/image/image-20221021164334189.png
diff --git a/...13.代码贡献/image/image-20221021165220086.png → ...13.社区支持/image/image-20221021165220086.png b/...13.代码贡献/image/image-20221021165220086.png → ...13.社区支持/image/image-20221021165220086.png
diff --git a/...13.代码贡献/image/image-20221021165804529.png → ...13.社区支持/image/image-20221021165804529.png b/...13.代码贡献/image/image-20221021165804529.png → ...13.社区支持/image/image-20221021165804529.png
diff --git a/...13.代码贡献/image/image-20221021165903669.png → ...13.社区支持/image/image-20221021165903669.png b/...13.代码贡献/image/image-20221021165903669.png → ...13.社区支持/image/image-20221021165903669.png
diff --git a/...13.代码贡献/image/image-20221021170033561.png → ...13.社区支持/image/image-20221021170033561.png b/...13.代码贡献/image/image-20221021170033561.png → ...13.社区支持/image/image-20221021170033561.png
diff --git a/...13.代码贡献/image/image-20221022090648166.png → ...13.社区支持/image/image-20221022090648166.png b/...13.代码贡献/image/image-20221022090648166.png → ...13.社区支持/image/image-20221022090648166.png
diff --git a/...13.代码贡献/image/image-20221022090821858.png → ...13.社区支持/image/image-20221022090821858.png b/...13.代码贡献/image/image-20221022090821858.png → ...13.社区支持/image/image-20221022090821858.png
diff --git a/docs/develop/13.社区支持/image/vscode-git-sign-off.png b/docs/develop/13.社区支持/image/vscode-git-sign-off.png
diff --git a/docs/develop/13.社区支持/support.md b/docs/develop/13.社区支持/support.md
@@ -0,0 +1,18 @@
+# 支持支持
+
+核心开发团队和社区成员活跃于以下渠道，您可以从以下方式获得帮助。
+
+## 故障诊断
+
+如果您不确定问题是什么，需要帮助诊断，建议按照如下步骤：
+
+- 将飞行日志上传到[Flight Log Review](https://logs.px4.io/)，查看报告分析报告。
+- 在 [Github Discuss](https://github.com/nextpilot/nextpilot-flight-control/discussions) 查看是否已有类似问题，如果没有请提交一个讨论，如果问题是由 bug 引起的，开发团队可能会提示您提一个 Issue。
+
+- 在 [Github Issue](https://github.com/nextpilot/nextpilot-flight-control/issues/) 提交一个问题反馈，包含问题的详细的描述（足以让问题复现）以及您在[Flight Log Review](https://logs.px4.io/)的日志链接。
+
+## 扫码加群
+
+扫码加入 NextPilot 社区支持群，我们会提供相关技术支持，全力为大家答疑解惑。
+
+![](https://www.nextpilot.org/community/add-to-group.jpeg)
diff --git a/nextpilot-flight-control.code-workspace b/nextpilot-flight-control.code-workspace
@@ -55,13 +55,14 @@
 		"C_Cpp.clang_format_fallbackStyle": "LLVM",
 		"C_Cpp.formatting": "clangFormat",
 		"C_Cpp.autocompleteAddParentheses": true,
-		"C_Cpp.default.cppStandard": "c++14",
+		"C_Cpp.default.cppStandard": "c++17",
 		"C_Cpp.default.cStandard": "c11",
 		// git
 		"git.rebaseWhenSync": true,
 		"git.autofetch": "all",
 		"git.pruneOnFetch": true,
 		"git.pullBeforeCheckout": true,
+		"git.alwaysSignOff": true,
 		// toml
 		"evenBetterToml.formatter.trailingNewline": true,
 		"evenBetterToml.formatter.alignComments": true,
@@ -119,9 +120,10 @@
 		"RTT_Studio.Debuger.stlinkGdbServerExecutable": "C:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/STMicroelectronics/ST-LINK_Debugger/1.6.0",
 		"RTT_Studio.Debuger.QEMU.Location": "C:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/RealThread/QEMU/4.2.0.4",
 		"files.associations": {
-			"Kconfig": "kconfig",
 			".clang-format-ignore": "ignore",
 			"*.jinja": "jinja",
+			"*.m": "matlab",
+			"Kconfig": "kconfig",
 			"*.hpp.jinja": "jinja-cpp",
 			"random": "c",
 			"charconv": "cpp",
@@ -155,7 +157,12 @@
 			"xmemory": "cpp",
 			"ranges": "cpp",
 			"span": "cpp",
-			"vector": "cpp"
+			"vector": "cpp",
+			"any": "cpp",
+			"compare": "cpp",
+			"format": "cpp",
+			"regex": "cpp",
+			"variant": "cpp"
 		},
 		"RTT_Studio.Debuger.Gdb_Path": ""
 	},