Repository navigation
Enhance documentation on thread safety and versioning policies - #40
Merged
Merged
Conversation
新增 docs/usage/07-thread-safety.md： - 总契约 5 条规则（同引擎并发不安全 / 同模型并发 forward 不安全 / Tensor 无内部同步 / 不同引擎实例互不干扰 / GpuBackend 创建回收线程安全） - CPU 引擎：全局线程池 oversubscribe 风险 + 并发 forward 不安全的具体根源 （sync_readback_slots_ 数据竞争、层 backward 缓存覆写） - GPU 引擎：单命令缓冲裸录制无锁、已加锁部分的清单（不构成并发口径）、 thread_local 录制图的边界、可并行形态（单推理线程 + 队列） - 全局资源共享表 + 服务化设计模板 + 演进口径（不会静默改并发语义） README 与 docs 索引加条目。
新增 docs/todo/33-version-branch-and-release-policy.md（32 号已被 feature 分支 RFC 文档占用，故取 33），固化三条规则： ① 版本号规则 v1.<API 变化>.<漏洞修复>，版本权威 = git tag（另注明历史遗留的 非规范 tag v.1.3.0 / nightly / archive/* 不属版本序列）； ② 发布版本号必须由人提出，agent 不得擅自决定版本号或执行发布动作 （git tag / gh release / project(VERSION) 定档 / release note 定稿）； ③ dev 及功能分支从不写版本号，定档与发布只发生在 main。 入口只留引用，规则正文独立成文： - AGENTS.md：文首加「开发规范/发布要求只给引用」行；§11 补 todo/24/25/26/28/ 29/30/33 与 usage/07 索引行；release-notes 行拆为「规范+索引」与「逐册」 两行且不再写死当前版本 - CONTRIBUTING.md §0 加「提发布/定版本号」入口，§4 分支表后加三条规则摘要 - docs/README、docs/todo/README、todo/25 关联、release-notes/README（细则 6） 补引用；todo/README 编号规则改为「新增接当前最大号」（不再写死 02…31） 过时信息清理（2026-10-30 实测刷新）： - 18-roadmap §2：版本行 v1.12.0 → v1.13.0（tag/VERSION/覆盖范围，复现命令改 git tag --list 'v1.*'，表内管道已转义）；include 82/44681、src 90/31730、 docs 67 篇、ctest 64/62、最大源文件 2797/1981 - ctest 计数三处互相矛盾的旧值（18 §8.1「54/41/52」、18 §8.2 规则硬编码、 CONTRIBUTING 自查「52/54」、todo/12 头部「67/69/56」、AGENTS §11「69/67」） 统一为 64（GPU 树）/ 62（无 Vulkan 树）= 51 目标 + 13 变体（2026-10-26 24e0599 下沉 7 测试后口径）；12 号删除失效的「AGENTS §7 枚举」指针， 标注 error_macro/kvrec/nnvocab/dataset 四测试已迁 extern/* 子仓 - docs/README release-notes 覆盖范围 → v1.5.0…v1.13.0；CMakeLists 注释去掉 写死的「当前 v1.12.0」（仅注释，无功能影响） - 历史记录行（已完成项、history、release note、带日期实测）按 18 §2 口径说明 原样保留
# Conflicts: # CONTRIBUTING.md # README.md
规范成文（docs/contributors/documentation-standard.md，此前无规范）：
- 分册职责矩阵 + 编号制度成文（internal/ = 稳定 ID 跳号；调用者分册 =
阅读顺序连续编号；contributors/ = 无编号主题名）
- 单篇头部模板强制（读者 / 一句话结论 / 状态）+ 封闭状态词表
- 内容标注体系：代码示例角色（example api / snippet / cli）、API 符号
反引号口径、事实三分（机械事实 / 设计意图 / 未验证主张）
- 历史性记载禁令：history/ 之外（含代码注释）不得出现"已在 commit xxx
修复"式叙事，一律改写为当前事实
目录重构：
- docs/todo/ → docs/internal/（原名只覆盖待办语义，实际承载设计/台账）
- 新增 docs/contributors/ 分册：cpp-standards（原 todo/10）、pitfalls
（原 todo/08）、release-policy（原 todo/33）、release-requirements
（原 todo/25）+ 新写 documentation-standard
- docs/development/ 编号按阅读顺序重排（cmake-integration→01、
cpp-api-manual→02、write-a-custom-layer→03、compute-engine→04、
vulkan-backend-map→06、engine-ownership→07、rapt→08、ergonomics→09），
删除转发页 08-object-lifetimes（真源 = 07）
- 全仓引用同步（136 个文件，含 gui.py/CMakeLists/bench 注释）
机器审查升级（scripts/doc_audit.py，跨平台，取代 ps1 口径）：
- 移植 ps1 A–D/F 类（文件/链接、已删符号、数字断言、CLI 参数、符号/测试名）
- 新增 E 类（头部模板 + 状态词 + 索引登记）、G 类（提取全部 408 个代码块
生成人工复核清单）、H 类（历史性记载，行内 allow 豁免机制）
- 全绿；ps1 保留至 Windows 侧迁移完成
根 README 重写为项目介绍（30 秒决策框架）：
- 图标（assets/icon-{dark,light}.svg）+ 亮点表 + "它不做什么"诚实边界
+ 最短可跑路径 + <details> 折叠次要信息；文档索引职责移交 docs/README.md
其余：全部 docs/**.md 补齐头部模板与状态词；release-notes 逐册登记；
history.md 归档历次整理叙事（docs/README §3/§4 迁出）
- 文档审计唯一实现 = scripts/doc_audit.py（ps1 的 A–D/F 类已移植并扩展 E/G/H 三类；当前口径引用同步为 doc_audit.py，历史台账/实跑记录保持原样） - ps1 加入 doc_audit.py 的历史白名单（历史文档提及不再报警） - .template/ 的图标 zip 交付原件移除（README 实际引用的解压版在 assets/， 已随上一提交入库）
EthanPeng-2048
added a commit
that referenced
this pull request
Oct 30, 2026
Merge pull request #40 from neuralnet-cpp-dev/main
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Merge
maindoc optimize to dev