docs: update CONTRIBUTING.md with formatting fixes, AI dev guide, and docs guide-pytorch-AtomGit

已合并

docs: update CONTRIBUTING.md with formatting fixes, AI dev guide, and docs guide #36350

chenrayray创建于 5月21日从chenrayray/pytorch： v2.12.0-contrib 合入到 Ascend/pytorch： v2.12.0

docs: update CONTRIBUTING.md with formatting fixes, AI dev guide, and docs guide #36350

已合并

chenrayray创建于 5月21日

从chenrayray/pytorch v2.12.0-contrib合入到Ascend/pytorch v2.12.0

共 1 个文件变更+163-39

MCONTRIBUTING.md+163-39

	@@ -8,7 +8,7 @@ PyTorch 是基于 Ascend NPU 的深度学习框架发行版，针对华为昇腾
8		8
9	### 项目架构	9	### 项目架构
10		10
11	-```	11	+```text
12	pytorch	12	pytorch
13	├── docs/ # 项目文档	13	├── docs/ # 项目文档
14	├── ci/ # CI 构建脚本	14	├── ci/ # CI 构建脚本
	@@ -35,17 +35,17 @@ pytorch
35		35
36	### 核心模块说明	36	### 核心模块说明
37		37
38	-\| 模块 \| 说明 \|	38	+\| 模块 \| 说明 \|
39	-\|------\|------\|	39	+\|----------------------------\|--------------------------------------------------------------------------\|
40	-\| `torch_npu/csrc/core/npu` \| NPU 核心组件：事件管理(NPUEvent)、流管理(NPUStream)、图执行(NPUGraph)、设备守卫(NPUGuard)、内存管理 \|	40	+\| `torch_npu/csrc/core/npu` \| NPU 核心组件：事件管理(NPUEvent)、流管理(NPUStream)、图执行(NPUGraph)、设备守卫(NPUGuard)、内存管理 \|
41	-\| `torch_npu/csrc/aten` \| ATen 算子 NPU 后端：算子注册、调度、实现适配 \|	41	+\| `torch_npu/csrc/aten` \| ATen 算子 NPU 后端：算子注册、调度、实现适配 \|
42	-\| `torch_npu/csrc/framework` \| 算子命令框架：OpCommand、Kernel 调度、算子构建器 \|	42	+\| `torch_npu/csrc/framework` \| 算子命令框架：OpCommand、Kernel 调度、算子构建器 \|
43	-\| `torch_npu/npu/aclnn` \| ACLNN 算子 Python 接口：AscendCL NPU 算子库封装 \|	43	+\| `torch_npu/npu/aclnn` \| ACLNN 算子 Python 接口：AscendCL NPU 算子库封装 \|
44	-\| `torch_npu/npu/amp` \| 自动混合精度：GradScaler、FP16/BF16 支持 \|	44	+\| `torch_npu/npu/amp` \| 自动混合精度：GradScaler、FP16/BF16 支持 \|
45	-\| `torchnpugen` \| 代码生成工具：自动微分代码生成、代码模板 \|	45	+\| `torchnpugen` \| 代码生成工具：自动微分代码生成、代码模板 \|
46	-\| `examples` \| 示例代码：分布式通信、模型推理、ResNet 示例 \|	46	+\| `examples` \| 示例代码：分布式通信、模型推理、ResNet 示例 \|
47	-\| `third_party/op-plugin` \| 算子插件：自定义算子实现、PyTorch 算子覆盖 \|	47	+\| `third_party/op-plugin` \| 算子插件：自定义算子实现、PyTorch 算子覆盖 \|
48	-\| `test/npu` \| NPU 功能测试：设备管理、内存分配、算子测试 \|	48	+\| `test/npu` \| NPU 功能测试：设备管理、内存分配、算子测试 \|
49		49
50	## 贡献方式	50	## 贡献方式
51		51
	@@ -68,6 +68,7 @@ pytorch
68	Issue 类型：需求/功能建议	68	Issue 类型：需求/功能建议
69		69
70	需要包含的内容：	70	需要包含的内容：
		71	+
71	- 功能背景：该功能解决什么问题、能为用户带来什么价值	72	- 功能背景：该功能解决什么问题、能为用户带来什么价值
72	- 功能描述：详细描述建议的功能	73	- 功能描述：详细描述建议的功能
73	- 设计方案：技术思路、关键模块设计、上下游组件关系	74	- 设计方案：技术思路、关键模块设计、上下游组件关系
	@@ -78,6 +79,7 @@ pytorch
78	如果您发现 Bug 或文档问题，我们真诚欢迎您的反馈和修复建议。	79	如果您发现 Bug 或文档问题，我们真诚欢迎您的反馈和修复建议。
79		80
80	Bug Report 格式：	81	Bug Report 格式：
		82	+
81	- 环境信息：PyTorch 版本、OS、Python 版本、CANN 版本等	83	- 环境信息：PyTorch 版本、OS、Python 版本、CANN 版本等
82	- 问题描述：添加标签以便在问题仪表板上突出显示	84	- 问题描述：添加标签以便在问题仪表板上突出显示
83	- 复现步骤：尽可能详细地描述如何重现问题	85	- 复现步骤：尽可能详细地描述如何重现问题
	@@ -85,6 +87,7 @@ pytorch
85	- 给审稿人的特别说明：如有任何特殊情况	87	- 给审稿人的特别说明：如有任何特殊情况
86		88
87	修复流程：	89	修复流程：
		90	+
88	1. 在 Issue 中找到对应的 Bug 描述	91	1. 在 Issue 中找到对应的 Bug 描述
89	2. 评论 `/assign` 认领该任务	92	2. 评论 `/assign` 认领该任务
90	3. 创建分支进行修复	93	3. 创建分支进行修复
	@@ -108,16 +111,16 @@ pytorch
108		111
109	2. 克隆到本地：	112	2. 克隆到本地：
110		113
111	-```bash	114	+ ```bash
112	-git clone https://gitcode.com/<your-username>/pytorch.git	115	+ git clone https://gitcode.com/<your-username>/pytorch.git
113	-cd pytorch	116	+ cd pytorch
114	-```	117	+ ```
115		118
116	3. 创建开发分支：	119	3. 创建开发分支：
117		120
118	-```bash	121	+ ```bash
119	-git checkout -b {new_branch_name} origin/master	122	+ git checkout -b {new_branch_name} origin/master
120	-```	123	+ ```
121		124
122	4. 代码开发：请遵循 [代码规范](#代码规范)	125	4. 代码开发：请遵循 [代码规范](#代码规范)
123		126
	@@ -165,6 +168,7 @@ git checkout -b {new_branch_name} origin/master
165	### 环境搭建与编译	168	### 环境搭建与编译
166		169
167	编译构建：	170	编译构建：
		171	+
168	```bash	172	```bash
169	# 安装依赖并编译	173	# 安装依赖并编译
170	bash ci/build.sh --python=3.10	174	bash ci/build.sh --python=3.10
	@@ -179,10 +183,72 @@ cmake ..
179	make -j$(nproc)	183	make -j$(nproc)
180	```	184	```
181		185
		186	+### 编译加速技巧
		187	+
		188	+#### 使用 Ninja 构建
		189	+
		190	+默认情况下，CMake 使用 Makefile 生成器。安装 Ninja 构建系统可以显著加快编译速度。
		191	+
		192	+本项目 `setup.py` 会自动检测系统中是否安装了 Ninja：如果环境变量 `CMAKE_GENERATOR` 设置为 `ninja`，或者 `ninja` 命令在 `PATH` 中可用，将自动使用 Ninja 作为构建系统。
		193	+
		194	+```bash
		195	+pip install ninja
		196	+```
		197	+
		198	+安装 Ninja 后，编译即可自动生效，无需额外配置。如果之前已经编译过，安装 Ninja 后需要先执行一次清理：
		199	+
		200	+```bash
		201	+python setup.py clean
		202	+```
		203	+
		204	+#### 使用 Mold 链接器
		205	+
		206	+在频繁修改单个文件并重新编译的开发循环中，链接时间会占据主导。大多数 Linux 发行版自带的系统链接器（GNU `ld`）速度较慢，使用更快的链接器可以显著改善构建体验。
		207	+
		208	+本项目的 `CMakeLists.txt` 已内置链接器自动检测逻辑：优先检测 mold 链接器，若存在则自动启用（`-fuse-ld=mold`）。
		209	+
		210	+```bash
		211	+sudo apt install mold
		212	+# 或从源码安装：https://github.com/rui314/mold
		213	+```
		214	+
		215	+安装后重新编译即可自动生效。若需确认链接器是否正确启用，可检查编译输出中的链接选项是否包含 `-fuse-ld=mold`。
		216	+
		217	+#### 使用 CCache
		218	+
		219	+即使依赖跟踪基于文件修改时间，仍有许多场景下文件会被重复编译。使用 ccache 可以有效避免重复编译，节省大量时间。
		220	+
		221	+本项目的 `CMakeLists.txt` 已内置 ccache 自动检测逻辑，安装 ccache 后即可自动启用。但建议根据自身环境调整 ccache 配置（如缓存目录、缓存大小、压缩等）以获得最佳效果：
		222	+
		223	+```bash
		224	+sudo apt install ccache
		225	+# 或
		226	+sudo yum install ccache
		227	+```
		228	+
		229	+验证 ccache 是否生效：连续执行两次完整编译，第二次应明显快于第一次。如果未生效，可检查 `build/CMakeCache.txt` 中的 `CMAKE_C_COMPILER_LAUNCHER` 和 `CMAKE_CXX_COMPILER_LAUNCHER` 变量是否包含 ccache：
		230	+
		231	+```cmake
		232	+//C compiler launcher
		233	+CMAKE_C_COMPILER_LAUNCHER:PATH=/usr/bin/ccache
		234	+
		235	+//CXX compiler launcher
		236	+CMAKE_CXX_COMPILER_LAUNCHER:PATH=/usr/bin/ccache
		237	+```
		238	+
		239	+#### 仅编译所需目标
		240	+
		241	+如果只需重新构建 `torch_npu.so`，可以在 build 目录下直接指定目标，避免全量构建：
		242	+
		243	+```bash
		244	+cd build && ninja torch_npu
		245	+```
		246	+
		247	+如果未安装 Ninja，将 `ninja` 替换为 `make` 即可。
		248	+
182	### 本地静态检查	249	### 本地静态检查
183		250
184	-项目使用 [lintrunner](https://github.com/suo/lintrunner) 进行静态检查，支持在本地运行与 CI 完全一致的检查项，	251	+项目使用 [lintrunner](https://github.com/suo/lintrunner) 进行静态检查，支持在本地运行与 CI 完全一致的检查项，包括 Python 代码风格（Flake8、Ruff、PYFMT）、C++ 格式（ClangFormat、ClangTidy）、拼写检查（Codespell）等。
185	-包括 Python 代码风格（Flake8、Ruff、PYFMT）、C++ 格式（ClangFormat、ClangTidy）、拼写检查（Codespell）等。
186		252
187	#### 安装依赖	253	#### 安装依赖
188		254
	@@ -217,23 +283,24 @@ git diff --name-only HEAD \| xargs lintrunner
217		283
218	> 提示：`--take` 参数可指定只运行部分检查项，常用项如下：	284	> 提示：`--take` 参数可指定只运行部分检查项，常用项如下：
219	>	285	>
220	-> \| 代码 \| 说明 \|	286	+> \| 代码 \| 说明 \|
221	-> \|------\|------\|	287	+> \|---------------\|----------------------------------------------------------------\|
222	-> \| `FLAKE8` \| Python 语法与风格检查 \|	288	+> \| `FLAKE8` \| Python 语法与风格检查 \|
223	-> \| `RUFF` \| Python 快速 lint 与 import 排序 \|	289	+> \| `RUFF` \| Python 快速 lint 与 import 排序 \|
224	-> \| `PYFMT` \| Python 代码格式化（usort + ruff-format） \|	290	+> \| `PYFMT` \| Python 代码格式化（usort + ruff-format） \|
225	-> \| `CLANGFORMAT` \| C++ 代码格式化 \|	291	+> \| `CLANGFORMAT` \| C++ 代码格式化 \|
226	-> \| `CLANGTIDY` \| C++ 静态分析 \|	292	+> \| `CLANGTIDY` \| C++ 静态分析 \|
227	-> \| `SPACES` \| 行尾空格检查 \|	293	+> \| `SPACES` \| 行尾空格检查 \|
228	-> \| `TABS` \| Tab 字符检查 \|	294	+> \| `TABS` \| Tab 字符检查 \|
229	-> \| `NEWLINE` \| 文件末尾换行检查 \|	295	+> \| `NEWLINE` \| 文件末尾换行检查 \|
230	-> \| `CODESPELL` \| 拼写检查, 如果是误报可以将误报词按照字典序添加至 `tools/linter/dictionary.txt` 后再重新检查 \|	296	+> \| `CODESPELL` \| 拼写检查, 如果是误报可以将误报词按照字典序添加至 `tools/linter/dictionary.txt` 后再重新检查 \|
231		297
232	更多执行命令可参照[lintrunner wiki](https://github.com/pytorch/pytorch/wiki/lintrunner)。	298	更多执行命令可参照[lintrunner wiki](https://github.com/pytorch/pytorch/wiki/lintrunner)。
233		299
234	### PR 合入要求	300	### PR 合入要求
235		301
236	合入检查清单（详细要求参考 [PR 模板](./.gitcode/PULL_REQUEST_TEMPLATE.md)）：	302	合入检查清单（详细要求参考 [PR 模板](./.gitcode/PULL_REQUEST_TEMPLATE.md)）：
		303	+
237	- [ ] 代码编译通过	304	- [ ] 代码编译通过
238	- [ ] 静态检查通过（CppLint、CppCheck 等）	305	- [ ] 静态检查通过（CppLint、CppCheck 等）
239	- [ ] UT 测试用例通过	306	- [ ] UT 测试用例通过
	@@ -246,12 +313,14 @@ git diff --name-only HEAD \| xargs lintrunner
246	### 功能验证指导	313	### 功能验证指导
247		314
248	测试用例位置：	315	测试用例位置：
		316	+
249	- `test/npu/` - NPU 功能测试	317	- `test/npu/` - NPU 功能测试
250	- `test/nn/` - 网络层测试	318	- `test/nn/` - 网络层测试
251	- `test/distributed/` - 分布式测试	319	- `test/distributed/` - 分布式测试
252	- `test/dynamo/` - 编译器测试	320	- `test/dynamo/` - 编译器测试
253		321
254	运行测试（详细说明参考 [测试文档](./test/README.md)）：	322	运行测试（详细说明参考 [测试文档](./test/README.md)）：
		323	+
255	```bash	324	```bash
256	# 安装测试依赖	325	# 安装测试依赖
257	pip3 install -r test/requirements.txt	326	pip3 install -r test/requirements.txt
	@@ -282,21 +351,76 @@ python ci/access_control_test.py --all
282	- 静态检查异常：请依照提示查找代码中的问题并解决（如代码风格、潜在 Bug 等）	351	- 静态检查异常：请依照提示查找代码中的问题并解决（如代码风格、潜在 Bug 等）
283	- UT 测试未通过：请根据提示查找测试用例不通过项并检查原因	352	- UT 测试未通过：请根据提示查找测试用例不通过项并检查原因
284		353
		354	+### AI辅助研发
		355	+
		356	+PyTorch NPU 项目鼓励使用 AI 辅助研发与文档开发，以提升贡献效率。我们提供了昇腾官方的 agent-skills 仓库，其中包含一系列适用于昇腾生态的 AI Agent Skill 配置，可帮助您在开发中更好地利用 AI 编码助手。
		357	+
		358	+- agent-skills 仓库：[https://gitcode.com/Ascend/agent-skills](https://gitcode.com/Ascend/agent-skills)
		359	+- 该仓库提供了昇腾芯片场景下常用的 Skill 模板和工具，可用于代码生成、问题诊断、性能分析等场景。
		360	+- 仓库中的 skills 持续更新中，同时欢迎贡献新的 Skill 或对现有 Skill 提出改进建议。
		361	+
		362	+使用 AI 辅助研发时请注意：
		363	+
		364	+- AI 生成的代码仍需人工审查，确保代码质量、安全性和正确性。
		365	+- 遵循项目的[代码规范](#代码规范)和[单元测试指南](#单元测试指南)。
		366	+- 提交的代码需通过门禁检查（编译、静态检查、UT 测试等）。
		367	+
		368	+### 文档开发说明
		369	+
		370	+#### 文档承载方式
		371	+
		372	+本项目的文档采用 Markdown 格式，存放于仓库的 `docs/zh/` 目录下，随代码一同托管在 GitCode 平台。
		373	+
		374	+> 注意：文档承载在长稳版本的分支中，如 `v2.7.1`。如果您需要查看或修改文档，请切换到对应的长稳版本分支进行操作。
		375	+
		376	+文档主要包含以下类目：
		377	+
		378	+- 安装指南（`installation_guide/`）：环境准备、源码编译、pip 安装等说明。
		379	+- 快速入门（`quick_start/`）：快速上手教程。
		380	+- 原生 API 文档（`native_apis/`）：各版本 PyTorch 原生 API 支持情况。
		381	+- 框架特性指南（`framework_feature_guide_pytorch/`）：NPU 图模式、Inductor、内存优化等特性说明。
		382	+- 环境变量参考（`environment_variable_reference/`）：NPU 相关环境变量说明。
		383	+- 故障排除（`troubleshooting/`）：常见问题及错误码分析。
		384	+- 安全声明（`SECURITYNOTE.md`）：安全相关说明。
		385	+- 贡献指南（`CONTRIBUTING.md`）：本文档。
		386	+
		387	+#### 如何提交文档
		388	+
		389	+文档的提交流程与代码提交一致，请参考[贡献流程](#贡献流程)：
		390	+
		391	+1. Fork 仓库并在本地创建分支。
		392	+2. 在 `docs/zh/` 目录下新增或修改对应的 Markdown 文件。
		393	+3. 编写文档时注意：
		394	+ - 使用清晰、准确的中文表述。
		395	+ - 代码示例需确保可运行。
		396	+ - 遵循现有文档的格式和风格。
		397	+4. 提交 Pull Request，并在 PR 描述中说明文档变更内容。
		398	+
		399	+#### CI 文档检查
		400	+
		401	+提交文档的 Pull Request 后，CI 门禁会自动对变更的 Markdown 文件进行以下检查：
		402	+
		403	+- 换行符检查（NEWLINE）：确保文件末尾有且仅有一个换行符，且文件不包含多余的空行。
		404	+- 尾随空格检查（SPACES）：确保每行末尾没有多余的空格。
		405	+- 制表符检查（TABS）：确保文件中使用空格缩进而非制表符（Tab）。
		406	+- 拼写检查（CODESPELL）：通过 codespell 工具检查英文拼写错误。
		407	+
285	## 提交 Pull Request	408	## 提交 Pull Request
286		409
287	1. 推送代码到远程仓库：	410	1. 推送代码到远程仓库：
288		411
289	-```bash	412	+ ```bash
290	-git add .	413	+ git add .
291	-git status	414	+ git status
292	-git commit -m "Your commit title"	415	+ git commit -m "Your commit title"
293	-git commit -s --amend # 添加详细描述	416	+ git commit -s --amend # 添加详细描述
294	-git push origin {new_branch_name}	417	+ git push origin {new_branch_name}
295	-```	418	+ ```
296		419
297	2. 创建 Pull Request	420	2. 创建 Pull Request
298		421
299	在 GitCode 上创建 Pull Request，根据 [PR 模板](./.gitcode/PULL_REQUEST_TEMPLATE.md) 完整填写：	422	在 GitCode 上创建 Pull Request，根据 [PR 模板](./.gitcode/PULL_REQUEST_TEMPLATE.md) 完整填写：
		423	+
300	- 合入来源	424	- 合入来源
301	- 修改方案	425	- 修改方案
302	- 资料变更	426	- 资料变更