diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 770ed2ae7..ff6df08b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -289,6 +289,79 @@ Common fixtures are defined in `tests/conftest.py`, including `client` (initiali --- +## Maintainer Routing and Contribution Entry + +### Contributor-Facing Module Map + +If you are not sure where your question, issue, or PR belongs, start with this table: + +| Domain | Area | Primary Contact | +|--------|------|-----------------| +| Integration | Bot | `@yeshion23333` | +| Integration | OpenClaw Plugin | `@Mijamind719`, `@wlff123` | +| Platform | Framework / Multi-tenant / Resources / Session | `@qin-ctx` | +| Platform | Incremental / Scheduled Update | `@myysy` | +| Knowledge | Memory | `@chenjw` | +| Knowledge | Retrieval / Directory Semantics | `@zhoujh01` | +| Storage & Security | Virtual FS / File Encryption | `@chuanbao666`, `@baojun-zhang` | + +If the area is still unclear, mention one of the cross-module maintainers listed below. + +### Maintainer Routing Map + +Use this table when routing issues, PRs, or design questions to a more specific owner: + +| Domain | Subarea | Representative Paths or Topics | Primary Contact | Backup / Cross-Module | +|--------|---------|--------------------------------|-----------------|-----------------------| +| Integration | Bot Runtime | `bot/vikingbot`, `bot/bridge`, deployment scripts, bot docs | `@yeshion23333` | `@chenjw` | +| Integration | OpenClaw Plugin | `examples/openclaw-plugin`, installation, remote mode, compatibility | `@Mijamind719`, `@wlff123` | `@LinQiang391` | +| Platform | Server & Multi-tenant | `openviking/server`, `openviking/service`, auth, identity, admin, tenant boundary | `@qin-ctx` | `@MaojiaSheng` | +| Platform | Resource & Session Lifecycle | `openviking/resource`, `openviking/session`, resource ingestion, session lifecycle | `@qin-ctx` | `@MaojiaSheng` | +| Platform | Incremental & Scheduled Update | `openviking/resource/watch_manager.py`, `openviking/resource/watch_scheduler.py` | `@myysy` | `@qin-ctx` | +| Knowledge | Memory Engine | `openviking/session/memory`, `memory_extractor.py`, `memory_deduplicator.py` | `@chenjw` | `@qin-ctx` | +| Knowledge | Retrieval & Directory Semantics | `openviking/retrieve`, intent analysis, hierarchical retrieval, directory semantics | `@zhoujh01` | `@qin-ctx` | +| Storage & Security | VFS / AGFS Path Semantics | `openviking/storage`, `openviking/pyagfs`, filesystem behavior, path semantics | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` | +| Storage & Security | Encryption & Data Safety | `openviking/crypto`, file encryption, storage safety | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` | + +For areas without a stable owner yet, cross-module maintainers will help route the request first. + +### Cross-Module Maintainers + +- `@MaojiaSheng` +- `@qin-ctx` +- `@zhoujh01` + +Cross-module maintainers help with issue routing, cross-cutting design questions, and fallback review support. + +### How to Ask for Help + +- If you already know the affected module, mention it in the issue or PR description. +- If you are unsure about the module, describe the use case and affected behavior first. +- If you want to work on an issue, leave a comment before starting, especially for cross-module changes. +- If your PR spans multiple areas, call out the primary affected domain in the description. + +### Contribution Entry Labels + +Issue templates already classify reports such as `bug`, `enhancement`, and `question`. Maintainers may also use the following labels to make contribution entry clearer: + +| Label | Meaning | +|-------|---------| +| `good first issue` | Newcomer-friendly work with clear scope and acceptance criteria | +| `help wanted` | Tasks that benefit from contributors who already know the codebase or review style | +| `needs-design` | Work that needs maintainer clarification before implementation | +| `needs-review` | Pull requests waiting for the first review round | + +### Contributor Growth Path + +The project uses a practical contribution path so contributors can see what “next step” looks like: + +| Stage | Typical Signals | Common Next Step | +|-------|------------------|------------------| +| New Contributor | First issue or first PR, often docs, tests, or scoped fixes | Start with `good first issue` items and get familiar with local workflow | +| Active Contributor | One or more merged contributions | Pick up `help wanted` work in an area you already touched | +| Module Contributor | Repeated contributions in the same subarea | Help with triage, reproduction, docs, or review comments in that area | +| Backup Reviewer Candidate | Stable contribution record in one subarea | Help with first-pass review, routing, and contributor support | + ## Contribution Workflow ### 1. Create a Branch diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md index 2cb777f76..909f3d240 100644 --- a/CONTRIBUTING_CN.md +++ b/CONTRIBUTING_CN.md @@ -289,6 +289,79 @@ class TestAsyncOpenViking: --- +## 维护者路由与贡献入口 + +### 面向贡献者的模块地图 + +如果你还不确定问题、issue 或 PR 属于哪个方向,可以先看这张表: + +| 领域 | 模块 | 主要联系人 | +|------|------|------------| +| Integration | Bot | `@yeshion23333` | +| Integration | OpenClaw Plugin | `@Mijamind719`、`@wlff123` | +| Platform | Framework / Multi-tenant / Resources / Session | `@qin-ctx` | +| Platform | Incremental / Scheduled Update | `@myysy` | +| Knowledge | Memory | `@chenjw` | +| Knowledge | Retrieval / Directory Semantics | `@zhoujh01` | +| Storage & Security | Virtual FS / File Encryption | `@chuanbao666`、`@baojun-zhang` | + +如果还是无法判断归属,可以直接 @ 下方的跨模块维护支持成员。 + +### 面向维护者的路由表 + +当需要把 issue、PR 或设计问题路由到更具体的 owner 时,可以参考下表: + +| 领域 | 子域 | 代表路径或主题 | 主要联系人 | 备援 / 跨模块支持 | +|------|------|----------------|------------|-------------------| +| Integration | Bot Runtime | `bot/vikingbot`、`bot/bridge`、部署脚本、bot 文档 | `@yeshion23333` | `@chenjw` | +| Integration | OpenClaw Plugin | `examples/openclaw-plugin`、安装、remote mode、兼容性 | `@Mijamind719`、`@wlff123` | `@LinQiang391` | +| Platform | Server & Multi-tenant | `openviking/server`、`openviking/service`、auth、identity、admin、租户边界 | `@qin-ctx` | `@MaojiaSheng` | +| Platform | Resource & Session Lifecycle | `openviking/resource`、`openviking/session`、资源导入、session 生命周期 | `@qin-ctx` | `@MaojiaSheng` | +| Platform | Incremental & Scheduled Update | `openviking/resource/watch_manager.py`、`openviking/resource/watch_scheduler.py` | `@myysy` | `@qin-ctx` | +| Knowledge | Memory Engine | `openviking/session/memory`、`memory_extractor.py`、`memory_deduplicator.py` | `@chenjw` | `@qin-ctx` | +| Knowledge | Retrieval & Directory Semantics | `openviking/retrieve`、意图分析、分层检索、目录语义 | `@zhoujh01` | `@qin-ctx` | +| Storage & Security | VFS / AGFS Path Semantics | `openviking/storage`、`openviking/pyagfs`、文件系统行为、路径语义 | `@chuanbao666`、`@baojun-zhang` | `@zhoujh01` | +| Storage & Security | Encryption & Data Safety | `openviking/crypto`、文件加密、存储安全 | `@chuanbao666`、`@baojun-zhang` | `@zhoujh01` | + +对于暂时还没有稳定 owner 的方向,先由跨模块维护支持成员协助路由。 + +### 跨模块维护支持 + +- `@MaojiaSheng` +- `@qin-ctx` +- `@zhoujh01` + +跨模块维护支持成员主要负责 issue 路由、跨模块设计问题,以及 owner 繁忙时的补位 review。 + +### 如何获得帮助 + +- 如果你已经知道受影响模块,请在 issue 或 PR 描述中直接写明。 +- 如果暂时无法判断模块归属,优先描述使用场景和受影响行为。 +- 如果你想认领某个 issue,建议先留言说明,尤其是跨模块改动。 +- 如果你的 PR 涉及多个模块,请在描述中标明主要影响域。 + +### 贡献入口标签 + +Issue 模板已经会对 `bug`、`enhancement`、`question` 等问题类型做基础分类。为了让贡献入口更清晰,维护者还可能补充以下标签: + +| 标签 | 含义 | +|------|------| +| `good first issue` | 适合新贡献者上手,范围清晰且验收标准明确 | +| `help wanted` | 更适合已经熟悉仓库或 review 风格的贡献者参与 | +| `needs-design` | 实现前需要维护者先澄清设计边界 | +| `needs-review` | 正在等待首轮 review 的 PR | + +### 贡献成长路径 + +我们希望贡献成长路径足够实际,让贡献者能清楚看到下一步可以怎么参与: + +| 阶段 | 常见信号 | 下一步建议 | +|------|----------|------------| +| 新贡献者 | 第一次提 issue 或 PR,通常从文档、测试或小范围修复开始 | 从 `good first issue` 入手,熟悉本地开发和提交流程 | +| 活跃贡献者 | 已经有一个或多个合入贡献 | 在自己熟悉的模块下开始认领 `help wanted` | +| 模块贡献者 | 在同一子域持续贡献 | 开始参与该模块的 issue 分流、问题复现、文档补充或 review 建议 | +| 备援 Reviewer 候选 | 在某个子域形成稳定贡献记录 | 协助首轮 review、问题路由和贡献者支持 | + ## 贡献流程 ### 1. 创建分支