doccano 开源贡献实战指南：从 Bug 报告到 Pull Request 的完整开发工作流

数据标注后端前端【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址https://gitcode.com/gh_mirrors/do/doccano点击查看免费下载doccano 是一个面向机器学习从业者的开源文本标注工具后端基于 Django Django REST Framework前端基于 Nuxt.jsVue 2。本文依据仓库根目录下的 docs/CONTRIBUTING.md 展开结合仓库内的命令源码、配置与测试完整讲解发现问题 → 提交高质量 Issue → 搭建本地开发环境 → 编写并验证代码 → 提交 Pull Request的整条贡献链路。读完本文你将掌握 doccano 官方的开发工作流、全部初始化命令与代码规范检查工具能够独立参与 doccano 的缺陷修复与功能增强。贡献之前沟通先行遵守行为准则doccano 的贡献流程强调先讨论、后动手在修改任何内容之前应当先通过 Issue 与仓库维护者沟通你想做的改动确认方向后再提交代码。与此同时所有交互都必须遵守项目的行为准则Code of Conduct。这一前置流程的意义在于避免重复劳动——功能方向、接口设计或实现取舍未经确认就提交 PR很可能与维护者的规划冲突导致大量返工。先讨论、再实现是对维护者与社区其他贡献者时间的基本尊重。报告 Bug让问题可复现、可定位提交 Bug 报告前的自查清单在提交 Bug 报告之前请先完成以下三件事避免创建重复或无效的 Issue先查常见问题阅读仓库的 常见问题 FAQ确认你的问题不是已知的通用问题。搜索已有 Issue在 Issues 列表中检索确认该 Bug 是否已经被其他人报告过。使用 Bug 报告模板如果找不到已存在的同主题 Issue再新建 Issue并使用官方提供的 Bug 报告模板填写内容。如何撰写一份高质量的 Bug 报告一份好的 Bug 报告应当让维护者无需追问即可复现问题。doccano 官方建议在报告中包含以下要素清晰描述性的标题让维护者一眼看出问题所在。完整复现步骤尽可能详细地描述触发 Bug 的每一步操作并附上具体示例来演示这些步骤。观察到的行为与问题所在说明按步骤操作后你实际看到了什么并明确指出其中哪一点是异常的。期望行为及原因说明你期望看到什么行为以及为什么这是合理的预期。截图与 GIF 演示附上能演示操作过程和问题的截图或动图。性能 / 内存类问题附 CPU Profile如果问题与性能或内存相关请在报告中附带 CPU 性能分析数据。网络类问题附 DevTools 抓包如果问题与网络相关请附上 Chrome / Firefox / Safari 开发者工具中的网络活动记录。描述触发前上下文如果问题不是由某个特定动作触发的请说明在问题发生之前你正在做什么。建议增强把想法变成可执行的提案提交增强建议前的自查与 Bug 报告类似提交增强建议前同样需要先搜索 Issues确认该想法没有被讨论过如果找不到相关 Issue再使用官方模板新建。撰写增强建议的要素清单为了让维护者和其他贡献者充分理解你的提案官方建议在增强建议中包含清晰描述性的标题。逐步描述建议的增强内容越详细越好。具体示例用实例演示建议的功能或交互。当前行为与期望行为描述现状并解释你期望的改进。截图或动图用于说明步骤或指出提案涉及 doccano 的哪个界面部分。说明该增强对大多数用户的用处。列出其他同类标注工具中已存在的类似功能供维护者参考对比。注明你使用的 doccano 版本。注明操作系统名称与版本。开发工作流从 Fork 到合并的九步全流程doccano 采用典型的 GitHub Fork Pull Request 协作模型完整流程分为九步每一步都配有可执行命令。第 1 步Fork 仓库并克隆到本地点击仓库页面右上角的 Fork 按钮将doccano复制到你的 GitHub 账户下然后在本地克隆你自己的 fork$ git clone 你的 fork 仓库地址第 2 步添加 upstream 远端并保持同步把本地副本与原始上游仓库关联起来形成两个远端指向你 fork 的origin可读可写和指向原始仓库的upstream只读$ cd doccano $ git remote add upstream doccano 原始仓库地址之后要持续将 fork 与上游保持同步减少后续合并冲突的概率。第 3 步为每项工作创建独立分支每修复一个 Bug 或开发一个特性都从develop分支切出一个独立分支分支名要描述性强、有意义例如bugfix-for-issue-1234或improve-io-performance让其他人一眼看出你在做什么$ git checkout develop $ git pull develop master git push origin develop $ git checkout -b my-descriptive-branch-name分支粒度与命名直接决定了后续代码评审和合并的清晰度建议一个分支只承载一项聚焦的改动。第 4 步搭建后端开发环境Poetry Django Celerydoccano 后端是一个 Django 项目推荐使用 Poetry 在独立虚拟环境中安装依赖。原文档建议使用 Python 3.8以当前仓库 backend/pyproject.toml 的实际声明为准Python 版本要求为3.10,4.0Django 为^4.1.7。$ cd backend $ poetry install $ poetry shell依赖安装完成后依次执行 Django 管理命令完成数据库迁移与初始化$ python manage.py migrate $ python manage.py create_roles $ python manage.py create_admin --noinput --username admin --email adminexample.com --password password $ python manage.py runserver这几条命令在仓库中都有对应的源码实现值得深入了解migrate将 backend/api/migrations 及各应用migrations目录下的迁移文件应用到数据库。默认数据库配置在 backend/config/settings/base.py 中为 SQLitedb.sqlite3同时支持通过DATABASE_URL环境变量切换为 PostgreSQL、MySQL 等生产数据库。create_roles由 backend/roles/management/commands/create_roles.py 实现它从 Django settings 中读取三个角色名并幂等创建project_admin项目管理员、annotator标注员、annotation_approver标注审批员。这三个角色的默认值定义在 backend/config/settings/base.py 的ROLE_PROJECT_ADMIN/ROLE_ANNOTATOR/ROLE_ANNOTATION_APPROVER中可通过同名环境变量覆盖。角色数据模型见 backend/roles/models.py。create_admin由 backend/api/management/commands/create_admin.py 实现继承 Django 内置的createsuperuser命令并增加了--password参数以支持非交互式创建。源码中还内置了三层防护缺少--username或--password时报错退出使用默认密码password时输出警告提示尽快修改用户名已存在时提示并继续不会覆盖原有密码。这些行为都有对应测试用例验证见 backend/api/tests/test_commands.py。此外仓库还提供了wait_for_db命令backend/api/management/commands/wait_for_db.py用于阻塞等待数据库可用默认每 3 秒轮询一次、最多重试 60 次是容器化部署场景下常用的初始化前置命令。由于 doccano 的数据集导入 / 导出功能依赖 Celery 异步任务你需要在另一个终端中仍在backend目录下启动 Celery worker$ celery --appconfig worker --loglevelINFO --concurrency1从 backend/config/celery.py 可以看到Celery 应用名为config通过config_from_object读取CELERY_前缀的配置并自动发现各应用下的celery_tasks模块例如 backend/data_import/celery_tasks.py、backend/data_export/celery_tasks.py。开发环境下 broker 默认回退为 SQLite 数据库本身sqlasqlite:///...见 backend/config/settings/base.py因此本地无需额外安装 Redis 即可运行 worker。第 5 步搭建前端开发环境Node.js Yarn Nuxt.jsdoccano 前端基于 Node.js使用 Yarn 作为包管理器开发框架为 Nuxt.jsVue 2 TypeScript。先安装依赖$ cd frontend $ yarn install然后以热重载模式启动开发服务器$ yarn dev此时访问 http://127.0.0.1:3000/ 即可看到前端页面。前端与后端通过代理协同工作相关的脚本定义见 frontend/package.jsondev脚本运行nuxtNuxt 配置见 frontend/nuxt.config.js。第 6 步实现变更并运行质量检查编写代码时要保持改动聚焦、范围受控遵循下文风格指南中的约定边写边补充文档并运行既有测试、为新功能新增测试确保不破坏已有功能。后端质量检查通过 Poetry task 执行task 定义见 backend/pyproject.toml 的[tool.taskipy.tasks]$ poetry run task mypy # 静态类型检查 $ poetry run task flake8 # PEP8 风格检查pflake8跳过 migrations $ poetry run task black # 代码格式化检查black --check行宽 120 $ poetry run task isort # import 排序检查按 black profile $ poetry run task test # 运行全部测试python manage.py test --patterntest*.py这些任务与 backend/pyproject.toml 中的[tool.black]、[tool.flake8]、[tool.mypy]、[tool.isort]配置一一对应例如 black 行宽 120、flake8 忽略E203,E266,W503,E704、mypy 排除migrations与config目录、isort 采用blackprofile 并将api、roles、projects等内部应用标记为 first-party。测试分布在各个应用的 tests 目录下其中 backend/api/tests/test_commands.py 覆盖了create_admin命令的成功、缺参报错、默认密码警告等场景可作为为命令编写测试的参考范例。前端质量检查通过 Yarn 脚本执行$ yarn lintfix # ESLint 自动修复覆盖 .ts/.js/.vue $ yarn precommit # 等价于 yarn lint提交前检查 $ yarn fix:prettier # Prettier 自动格式化前端还提供yarn testJest 单元测试与yarn buildNuxt 生产构建详见 frontend/package.json。第 7 步推送提交到你的 fork将改动组织为原子化的 git 提交一次提交只做一件事然后推送到origin。不必等所有改动都最终定稿才推送——随时推送相当于给本地代码上了备份保险$ git push origin my-descriptive-branch-name第 8 步提交 Pull Request在 GitHub 上进入你的 fork切换到工作分支点击 New pull request 发起 PR若刚推送过仓库顶部通常会出现 Compare pull request 快捷按钮。提交时完整、清晰地填写 PR 模板仔细核对代码 diff确保没有混入无关改动提交后仓库的自动化流程CI会自动运行检查确保所有检查通过后再等待人工评审。第 9 步响应代码评审反馈PR 提交后维护者会进行代码评审可能要求补充修改或澄清也可能直接批准。评审往返是开源协作的常态请尽量及时响应如果一周左右没有收到回复可以在同一 PR 线程中礼貌地提醒维护者。风格指南Git 提交信息规范doccano 对 Git 提交信息有明确约定遵循这些规范能让提交历史更易读、更易检索使用现在时写 Add feature不写 Added feature。使用祈使语气写 Move cursor to...不写 Moves cursor to...。首行不超过 72 个字符。首行之后自由引用相关的 Issue 与 PR 编号建立改动与讨论的关联。结语参与 doccano 开发并不复杂先通过 Issue 与维护者确认方向再按本文的九步工作流搭建环境、实现改动、通过质量检查并提交 PR。从 docs/CONTRIBUTING.md 出发结合 backend/pyproject.toml、frontend/package.json 以及 backend/api/management/commands/create_admin.py 等源码你已经掌握了后端 Django 初始化、Celery worker 启动、前端 Nuxt 热重载、双端代码规范检查的完整命令链。无论是修复一个 Bug 还是新增一种标注能力这套流程都能保证你的贡献高质量地进入主干。赞分享数据标注后端前端【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址https://gitcode.com/gh_mirrors/do/doccano点击查看免费下载相关推荐FreshRSS 贡献指南从报告 Bug 到提交 Pull Request 的完整开发协作工作流FreshRSS 贡献指南从报告 Bug 到提交 Pull Request 的完整开发协作工作流 导读 本文基于 FreshRSS 官方法语贡献指南 doc后端前端CLIstatsmodels 贡献指南实战从 Bug 报告到 Pull Request 的完整流程statsmodels 贡献指南实战从 Bug 报告到 Pull Request 的完整流程 本篇指南以 statsmodels 仓库的 CONTRIBUTI数据分析数据科学科研Selectize.js 贡献指南从 Bug 报告到 Pull Request 的完整实战Selectize.js 贡献指南从 Bug 报告到 Pull Request 的完整实战 Selectize 是一个基于 jQuery 的可扩展自定义 sUI组件前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考