Contributing

贡献指南

为 wknet 贡献代码或文档时遵守以下约定。产品方向与命名见 内部边界。

代码风格

• C++17，符合 /kernel：无异常、无 RTTI
• 可用 namespace、类、RAII、轻量模板
• 避免直接 new/delete（除非 lib 内重载）；优先堆封装或 API Release
• lib 内禁止栈缓冲，用堆；高频缓冲常驻 Workspace
• 函数 noexcept；SAL 注解（_In_、_Out_、_Must_inspect_result_ 等）
• Debug/Release 均视警告为错误、最高警告等级；新增代码零警告
• 新功能必须补齐分级 Trace（Error / Warning / Info / Verbose|Max + 准确组件）

工作流

• 使用 pwsh，不要用 powershell
• 写完代码必须跑测试与 Debug 构建；禁止「冒烟走过场」
• 发现实现缺失时补全，不要忽视或降级
• 禁止把兜底 / 临时回退当作正式架构

提交

Conventional Commits：

feat:     新功能
fix:      缺陷
docs:     文档
style:    格式
refactor: 重构
test:     测试
chore:    构建/工具

docsite 提交：

1. docsite 变更与代码变更分两次提交
2. docsite 提交 message 以 docsite: 开头（触发 Wiki 单向同步）
3. 计划文档（docs/plans/*）仅在用户明确要求时提交

PR

Fork → 功能分支 → 提交 → Push → Pull Request。要求：风格一致、必要测试、相关文档、测试通过。

文档

• 公开文档以 docsite/ 为准；能力分类以 能力边界 为准
• 字段与签名以 include/wknet 为准，勿从过时 markdown 抄结构体
• 中英同批对等；勿留英文占位 stub

---

English

Contributing

Follow these conventions when contributing code or docs. Product direction and naming: Internals.

Code style

• C++17 under /kernel: no exceptions, no RTTI
• namespace, classes, RAII, and light templates are fine
• Avoid raw new/delete (unless overloaded in the lib); prefer heap wrappers or API Release
• No stack buffers in the lib — use the heap; keep hot buffers resident in Workspace
• Functions are noexcept; use SAL (_In_, _Out_, _Must_inspect_result_, …)
• Debug/Release treat warnings as errors at the highest level; new code is warning-free
• New features must add tiered Trace (Error / Warning / Info / Verbose|Max + accurate component)

Workflow

• Use pwsh, not powershell
• After code changes, run tests and a Debug build — no token smoke passes
• If an implementation is missing, complete it; do not skip or downgrade
• Do not treat fallbacks or temporary shims as architecture

Commits

Conventional Commits:

feat:     feature
fix:      bug fix
docs:     documentation
style:    formatting
refactor: refactor
test:     tests
chore:    build/tooling

docsite commits:

1. Split docsite changes from code changes into two commits
2. Prefix docsite commits with docsite: (triggers one-way Wiki sync)
3. Plan docs under docs/plans/* are committed only when the user asks

Pull requests

Fork → feature branch → commit → push → PR. Requirements: style match, necessary tests, related docs, green tests.

Documentation

• Public docs live under docsite/; capability classification is in the capability matrix
• Fields and signatures follow include/wknet; do not copy structs from stale markdown
• Ship Chinese and English together; no English placeholder stubs
• Ship Chinese and English together; no English stubs