From e3e6124e33b4d3b35ff6fd921d601333c99cd107 Mon Sep 17 00:00:00 2001 From: "peng.li24" <734991033@qq.com> Date: Sun, 13 Sep 2026 17:55:39 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20issue=20?= =?UTF-8?q?=E6=A8=A1=E7=89=88=E4=B8=8E=E7=B1=BB=E5=9E=8B=E6=A0=87=E7=AD=BE?= =?UTF-8?q?=E7=BA=A6=E5=AE=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 参考主流开源实践（epic / rfc / bug / feature / perf），把 issue 分类 收敛为六个类型标签 + 统一标题前缀格式 `[TYPE] : <描述>`。 - .github/ISSUE_TEMPLATE/config.yml 禁空白 issue，指向 spec - bug.yml 现象 / 复现 / 对应 spec 条款 / 后端 / 版本 - rfc.yml 动机 / 提案 / 影响面 / 备选方案 / 裁决记录 - epic.yml 目标 / 子任务清单 / 验收标准 / 依赖顺序 - feature.yml 需求 / 动机 / 落点 / 备选方案 - perf.yml 测量数据 / 后端 / 瓶颈分析 / 目标与代价 类型标签：EPIC、RFC、BUG、FEAT、PERF、DOCS。 Co-Authored-By: Claude Code --- .github/ISSUE_TEMPLATE/bug.yml | 51 ++++++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 +++ .github/ISSUE_TEMPLATE/epic.yml | 41 ++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/feature.yml | 37 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/perf.yml | 41 ++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/rfc.yml | 47 +++++++++++++++++++++++++++ 6 files changed, 222 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/epic.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yml create mode 100644 .github/ISSUE_TEMPLATE/perf.yml create mode 100644 .github/ISSUE_TEMPLATE/rfc.yml diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 00000000..e3bc3f20 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,51 @@ +name: Bug 报告 +description: 行为与 spec 或预期不符 +title: "[BUG] " +labels: ["BUG"] +body: + - type: markdown + attributes: + value: | + 先搜索是否已有同类 issue。spec 与实现不符时 **spec 为准**，实现是缺陷。 + - type: textarea + id: symptom + attributes: + label: 现象 + description: 实际发生了什么？与预期差在哪？ + validations: + required: true + - type: textarea + id: repro + attributes: + label: 复现 + description: 最小 kvlang 片段 + 运行命令 + 后端 DSN + placeholder: | + ```kv + rwfunc test() -> () { ... } + ``` + + `KVSPACE=shm:///tmp/x kvlang repro.kv` + validations: + required: true + - type: input + id: spec + attributes: + label: 对应 spec 条款 + description: 违反的是哪一条（`/lib/kvlang/spec/…` 路径或标题） + validations: + required: true + - type: dropdown + id: backend + attributes: + label: 后端 + description: 三后端不一致时请注明各自表现 + options: [shm, fs, redis, 多个（请说明差异）] + validations: + required: true + - type: input + id: version + attributes: + label: 版本 + description: git tag 或 commit（v0.2.18 等） + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..6a89eabe --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: 设计规范（spec） + url: https://github.com/array2d/kvlang/tree/master/stdlib/kvlang/spec + about: 语言事实以 stdlib/kvlang/spec/ 为唯一真相源；提 issue 前先查对应条款 diff --git a/.github/ISSUE_TEMPLATE/epic.yml b/.github/ISSUE_TEMPLATE/epic.yml new file mode 100644 index 00000000..52d63cdd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/epic.yml @@ -0,0 +1,41 @@ +name: Epic（大特性 / 父 issue） +description: 跨模块或多仓的大特性，由多个子 issue 组成，持续迭代 +title: "[EPIC] " +labels: ["EPIC"] +body: + - type: markdown + attributes: + value: | + Epic 是**追踪用父 issue**：本身不直接实现，只维护子任务清单与验收标准。 + 子任务各自单独开 issue，并在下方清单里链接。 + - type: textarea + id: goal + attributes: + label: 目标 + description: 这个 Epic 完成后，系统能达到什么状态？（可验证的表述） + validations: + required: true + - type: textarea + id: children + attributes: + label: 子任务 + description: 每行一条，用 `- [ ] #N 描述` 勾选式清单，便于追踪进度 + placeholder: | + - [ ] #123 子任务 A + - [ ] #124 子任务 B + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: 验收标准 + description: 满足哪些条件可关闭本 Epic（回归通过 / 三后端一致 / tag 已发等） + validations: + required: true + - type: textarea + id: dependencies + attributes: + label: 依赖与顺序 + description: 前置 issue、跨仓顺序约束（如后端先于 kvlang 发 tag） + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 00000000..b81c312c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,37 @@ +name: 功能请求 +description: 新增能力 / 语法 / 原语（含 stdlib 补全、原语新增） +title: "[FEAT] " +labels: ["FEAT"] +body: + - type: textarea + id: need + attributes: + label: 需求 + description: 想要什么能力？给出期望的 kvlang 写法（函数名/签名/示例）。 + placeholder: | + ```kv + kvspace·find(path, pattern) -> (keys:...) + ``` + validations: + required: true + - type: textarea + id: why + attributes: + label: 动机 + description: 没有它会怎样？现有能力为何不足（而不是换个写法就能解决）。 + validations: + required: true + - type: textarea + id: scope + attributes: + label: 落点 + description: 属哪一层（kvspace 原语 / layout 语法 / runtime rwir / stdlib rwfunc），是否需改 spec 条款 + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: 备选方案 + description: 现有写法能否替代？为什么不够。 + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/perf.yml b/.github/ISSUE_TEMPLATE/perf.yml new file mode 100644 index 00000000..1147ff66 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/perf.yml @@ -0,0 +1,41 @@ +name: 性能（测量 / 回归 / 优化） +description: 微基准、性能回归、热点优化 +title: "[PERF] " +labels: ["PERF"] +body: + - type: markdown + attributes: + value: | + kvlang 的性能瓶颈是架构本质（PC/帧/局部全落 KV 树、每步一次往返）， + 报数据时请区分「后端原语地板价」与「runtime 自身开销」。 + - type: textarea + id: measurement + attributes: + label: 测量 + description: 复现命令 + 数据（ns/op 或总耗时），标注后端与规模 + placeholder: | + `python3 benchmark/run.py -k iops --backends shm` + N=2000: kv-shm 15.996ms / python 91.4µs + validations: + required: true + - type: dropdown + id: backend + attributes: + label: 后端 + options: [shm, fs, redis, 多个（请说明）] + validations: + required: true + - type: textarea + id: analysis + attributes: + label: 分析 + description: 瓶颈定位（用 perf/rdtsc 定位到具体路径，而非猜测） + validations: + required: true + - type: textarea + id: expectation + attributes: + label: 目标与代价 + description: 期望收益、可接受代价（是否牺牲可读性/可恢复性），以及是否属既定地板价 + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml new file mode 100644 index 00000000..2b0f4454 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/rfc.yml @@ -0,0 +1,47 @@ +name: RFC（设计提案） +description: 需要讨论与裁决的设计变更（含语言语义、ABI、架构定位） +title: "[RFC] " +labels: ["RFC"] +body: + - type: markdown + attributes: + value: | + RFC 是**待裁决**的提案，不是已定方案。语言行为改动落地前必须先在 + `stdlib/kvlang/spec/` 写入条款，故提案里应指明要改哪些条款。 + - type: textarea + id: motivation + attributes: + label: 动机 + description: 现状哪里不对/不够用？举具体场景。 + validations: + required: true + - type: textarea + id: proposal + attributes: + label: 提案 + description: 具体改成什么。语言/ABI 层面的写法、签名、命名尽量给出。 + validations: + required: true + - type: textarea + id: impact + attributes: + label: 影响面 + description: | + 涉及哪些 spec 条款、哪些仓（kvlang / kvspace / kvspace-c / kvspace-durable）、 + 是否破坏兼容、是否需同步升 tag。 + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: 备选方案与取舍 + description: 考虑过但未采纳的方案，以及为什么。只留唯一正确方向时也要说明淘汰理由。 + validations: + required: true + - type: textarea + id: decision + attributes: + label: 裁决记录 + description: 讨论后填写：采纳/否决/改动后的结论（收敛后回填本条并更新标题/标签） + validations: + required: false From 9c43fcf02f0b68e387323cbb577ac8e0e53e0978 Mon Sep 17 00:00:00 2001 From: "peng.li24" <734991033@qq.com> Date: Sun, 13 Sep 2026 17:59:59 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E8=A1=A5=20roadmap=20=E6=A8=A1?= =?UTF-8?q?=E7=89=88=EF=BC=88=E9=A1=B9=E7=9B=AE=E7=BA=A7=E8=B7=AF=E7=BA=BF?= =?UTF-8?q?=E5=9B=BE=E8=BF=BD=E8=B8=AA=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 顶层追踪：主题 / 里程碑与 Epic / 完成判据 / 明确不做。 Co-Authored-By: Claude Code --- .github/ISSUE_TEMPLATE/roadmap.yml | 41 ++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/roadmap.yml diff --git a/.github/ISSUE_TEMPLATE/roadmap.yml b/.github/ISSUE_TEMPLATE/roadmap.yml new file mode 100644 index 00000000..93a13851 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/roadmap.yml @@ -0,0 +1,41 @@ +name: Roadmap（路线图 / 里程碑追踪） +description: 项目级方向与里程碑追踪，汇总若干 Epic +title: "[Roadmap] " +labels: ["EPIC"] +body: + - type: markdown + attributes: + value: | + Roadmap 是**顶层追踪 issue**：描述一段时间内的方向与里程碑，下挂若干 Epic。 + 只在方向调整时编辑，不记录日常进展（进展看子 issue）。 + - type: textarea + id: theme + attributes: + label: 主题 + description: 这一阶段的主线（一句话），以及为什么是现在。 + validations: + required: true + - type: textarea + id: epics + attributes: + label: 里程碑与 Epic + description: 每行 `- [ ] 里程碑 M1（目标日期）— #N Epic 描述` + placeholder: | + - [ ] M1 三后端 ABI 收敛 — #123 / #124 + - [ ] M2 编译器扩展可用 — #273 + validations: + required: true + - type: textarea + id: exit + attributes: + label: 完成判据 + description: 满足什么条件算这一阶段结束（发布 tag / 指标达标 / 跨仓一致） + validations: + required: true + - type: textarea + id: notdoing + attributes: + label: 明确不做 + description: 本阶段排除的方向，避免范围蔓延 + validations: + required: false