Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
87 lines (60 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

87 lines (60 loc) · 3.5 KB
Raw

贡献指南 / Contributing Guide

中文 · English

Jingwei / 经纬是 XUANSHU AI 的 Perception 产品仓库。贡献应保持 annotation-first、人工复核优先和公开发布边界清晰；一个 Pull Request 应尽量只解决一个问题。

Jingwei is the Perception product repository in XUANSHU AI. Contributions must preserve annotation-first, human-reviewed behavior and clear release boundaries. A pull request should normally solve one focused problem.

中文

开始前

请先确认变更属于一个主要模块：schema / examples、annotation platform、overlay、validator、OpenCV candidates、docs、release metadata 或 CI。涉及行为变化时建议先搜索或创建 Issue；安全问题请遵循 SECURITY.md，不要公开漏洞细节。

本地开发

要求 Python 3.11 或更高版本。

git clone https://github.com/PowellWells/jingwei.git
cd jingwei
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest -q

本地标注界面：

python -m hotarea_cv.server \
  --annotator-dir apps/annotator \
  --dataset-root ./data \
  --open-browser

数据与发布边界

  • visual_bbox 与 hit_bbox 分开保存并由人工确认。
  • Detector 只能输出 candidates，不能覆盖正式 annotation。
  • Validator 只报告问题，Overlay 只可视化。
  • 不把项目改造成 UI 自动化框架或第三方应用控制工具。
  • 不提交模型权重、训练截图、人工标注、私有评估集、云端日志、内部清单或凭据。
  • 第三方数据、模型与素材必须确认许可证、来源、署名和再分发条件。

Pull Request 清单

PR 描述必须说明：修改内容与原因、未修改的禁止范围、验收步骤、执行命令与结果、生成的 JSON/overlay/report、风险和未完成项。行为、数据格式或发布清单变化应补充测试并更新 CHANGELOG.md。

English

Before starting

Choose one primary area: schema/examples, annotation platform, overlay, validator, OpenCV candidates, docs, release metadata, or CI. Search for or open an issue before behavior changes. Follow SECURITY.md and do not disclose vulnerability details publicly.

Local development

Python 3.11 or later is required.

git clone https://github.com/PowellWells/jingwei.git
cd jingwei
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest -q

Start the local annotation UI:

python -m hotarea_cv.server \
  --annotator-dir apps/annotator \
  --dataset-root ./data \
  --open-browser

Data and release boundaries

  • Store visual_bbox and hit_bbox separately and require human confirmation.
  • The detector emits candidates only and must not overwrite formal annotations.
  • The Validator reports only; the Overlay visualizes only.
  • Do not turn the project into UI automation or third-party application control.
  • Do not commit model weights, training screenshots, human annotations, private evaluation sets, cloud logs, internal manifests, or credentials.
  • Confirm license, provenance, attribution, and redistribution rights for third-party data, models, and media.

Pull request checklist

Every PR must state what changed and why, which prohibited areas stayed untouched, verification steps, commands and results, generated JSON/overlay/report artifacts, risks, and unfinished work. Behavior, data-format, or release-manifest changes should include tests and update CHANGELOG.md.