贡献指南

August 5, 2026 · View on GitHub

感谢考虑为轻屿课表（mikcb）贡献代码、文档或教务适配。

开始之前

  1. 阅读 README.md 了解项目定位
  2. 阅读 LICENSE（GPL-3.0-or-later）——贡献的代码将按相同协议分发
  3. 行为准则见 CODE_OF_CONDUCT.md
  4. 安全问题见 SECURITY.md，不要在公开 Issue 中报告漏洞

命名说明

名称含义
GitHub 仓库 mikcb对外仓库名
pubspec university_timetable历史 Dart 包名，暂未更名
Android 包名 com.mutx163.qingyu应用 ID
产品名「轻屿课表」用户可见名称

开发环境

版本以 CI 与 .fvmrc 为准（当前稳定 Flutter 3.44.8；最低支持 Flutter 3.44.2 / Dart 3.12.2）。

# 可选：fvm use 3.44.8
flutter pub get
flutter run -d android --flavor dev

发版前必跑（与 CI / Release 一致）

dart format .      # 含文件末尾换行；勿用脚本手改 .dart 格式
flutter analyze --no-fatal-infos  # error/warning 失败，info 仅记录
flutter test

AI / 协作者约定见 .cursor/rules/dart-source-editing.mdc（Cursor 会自动注入）。

本地 AI / 协作者主线交付

对于在本地由 AI 或协作者直接完成的代码、配置、测试和文档任务，完成验证后必须主动将自己的提交合并回本地 main，不能把只存在于临时 worktree、detached HEAD 或个人分支中的提交作为最终交付。

  • 合并前检查 git status --short、当前分支和 HEAD，只处理本次任务自己的提交和文件。
  • 主线中与本次任务无关的未提交改动必须保留，不得使用 git add .、强制覆盖或清理命令。
  • 目标文件已有改动、主线基线发生变化或出现冲突时，停止自动合并并报告提交哈希与阻塞原因，禁止强行覆盖。
  • 合并成功后，在 main 上重新确认提交、工作区状态并运行必要的聚焦验证；只在用户明确要求时推送远程。

可选本地集成测试：

flutter test test_integration/

Android 签名：android/key.properties 与 keystore 不要提交；CI 使用 Secrets。

贡献流程

  1. Fork 本仓库
  2. 从 main 创建分支（feat/…、fix/…、docs/…）
  3. 小步提交，保持 diff 聚焦
  4. 推送并在 GitHub 开 Pull Request（会自动套用 PR 模板）
  5. 确保 CI 全绿

提交信息

推荐 Conventional Commits 风格，与现有历史一致：

  • feat: 新功能
  • fix: 修复
  • docs: 文档
  • test: 测试
  • chore: 构建 / CI / 杂项

贡献方向

应用本体（本仓库）

  • UI / HyperOS 体验
  • 课表逻辑、提醒、导入、云同步
  • 多语言（lib/l10n/*.arb）
  • 文档与官网（docs/）

教务系统适配（独立仓库）

网页登录导入脚本在 qingyu_warehouse 维护。请在该仓库开 Issue / PR。

不要提交的内容

  • API Key、签名文件、key.properties
  • 仅本地 IDE / Agent 配置（已在 .gitignore）
  • 与 PR 无关的大规模格式化

Issue 指引

使用 GitHub Issue 模板：

  • Bug 报告：复现步骤 + 版本 + 机型
  • 功能建议：用户场景优先
  • 教务适配：学校名称；代码请走 warehouse 仓库

发布

Maintainer 发版流程见 docs/RELEASE.md。外部贡献者通常不需要切 tag。

许可与第三方组件

获取帮助