企业官网建设流程全解析

• 数据标注
• 后端
• 前端

doccano 是一个面向机器学习从业者的开源文本标注工具，后端基于 Django + Django REST Framework，前端基于 Nuxt.js（Vue 2）。本文依据仓库根目录下的 docs/CONTRIBUTING.md 展开，结合仓库内的命令源码、配置与测试，完整讲解"发现问题 → 提交高质量 Issue → 搭建本地开发环境 → 编写并验证代码 → 提交 Pull Request"的整条贡献链路。读完本文，你将掌握 doccano 官方的开发工作流、全部初始化命令与代码规范检查工具，能够独立参与 doccano 的缺陷修复与功能增强。

贡献之前：沟通先行，遵守行为准则

doccano 的贡献流程强调先讨论、后动手：在修改任何内容之前，应当先通过 Issue 与仓库维护者沟通你想做的改动，确认方向后再提交代码。与此同时，所有交互都必须遵守项目的行为准则（Code of Conduct）。

这一前置流程的意义在于避免重复劳动——功能方向、接口设计或实现取舍未经确认就提交 PR，很可能与维护者的规划冲突，导致大量返工。先讨论、再实现，是对维护者与社区其他贡献者时间的基本尊重。

报告 Bug：让问题可复现、可定位

提交 Bug 报告前的自查清单

在提交 Bug 报告之前，请先完成以下三件事，避免创建重复或无效的 Issue：

1. 先查常见问题：阅读仓库的 常见问题 FAQ，确认你的问题不是已知的通用问题。
2. 搜索已有 Issue：在 Issues 列表中检索，确认该 Bug 是否已经被其他人报告过。
3. 使用 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 + Celery）

doccano 后端是一个 Django 项目，推荐使用 Poetry 在独立虚拟环境中安装依赖。原文档建议使用 Python 3.8+；以当前仓库 backend/pyproject.toml 的实际声明为准，Python 版本要求为>=3.10,<4.0，Django 为^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 "admin@example.com" --password "password" $ python manage.py runserver

这几条命令在仓库中都有对应的源码实现，值得深入了解：

• migrate将 backend/api/migrations 及各应用migrations目录下的迁移文件应用到数据库。默认数据库配置在 backend/config/settings/base.py 中为 SQLite（db.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 --app=config worker --loglevel=INFO --concurrency=1

从 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 数据库本身（sqla+sqlite:///...，见 backend/config/settings/base.py），因此本地无需额外安装 Redis 即可运行 worker。

第 5 步：搭建前端开发环境（Node.js + Yarn + Nuxt.js）

doccano 前端基于 Node.js，使用 Yarn 作为包管理器，开发框架为 Nuxt.js（Vue 2 + TypeScript）。先安装依赖：

$ cd frontend $ yarn install

然后以热重载模式启动开发服务器：

$ yarn dev

此时访问 http://127.0.0.1:3000/ 即可看到前端页面。前端与后端通过代理协同工作，相关的脚本定义见 frontend/package.json（dev脚本运行nuxt），Nuxt 配置见 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 --pattern="test*.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 test（Jest 单元测试）与yarn build（Nuxt 生产构建），详见 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 还是新增一种标注能力，这套流程都能保证你的贡献高质量地进入主干。

• 数据标注
• 后端
• 前端