Files
tjhlp-gitea/issue-templates/README.md
T
admin 68fb567cb3 feat: Issue 模板引导链接改指课程官网, 平台地址改由 public_url 注入
- 两个 config.yaml 的 contact_links 从 example.com 换成真实入口:
  官网《学会提问》/ 课程官网 / 平台提问速查, 让答疑平台与官网互相导流
- 模板支持 {{BASE_URL}}/{{ORG}}/{{REPO}} 占位符, 推送时替换,
  换学期建新组织不用改模板; 未配置时保留占位符并告警而不是推坏链接
- scripts: 新增 gitea.public_url(对外地址, 与 CLI 用的 url 区分),
  utils.web_base_url()/render_template_placeholders() 及单元测试
2026-09-11 17:07:11 +08:00

5.7 KiB

Issue Templates

结构化的 Issue 模板, 引导学生在提问前思考、规范问题描述, 减少低质量和重复提问。

设计理念

每个模板都包含以下引导机制:

  1. 强制先思考再提问 - 每个模板都有"你目前的理解"或"已尝试的方法"必填字段, 促使学生先尝试自己解决
  2. 减少重复提问 - 提交确认中要求"已搜索过已有 Issue"
  3. 结构化信息收集 - 使用 YAML 表单格式(dropdown、textarea with render 等), 比自由文本更规范
  4. 禁止空白 Issue - config.yaml 设置 blank_issues_enabled: false, 强制使用模板

目录结构

issue-templates/
├── general/                          general 仓库使用
│   └── .gitea/ISSUE_TEMPLATE/
│       ├── config.yaml               禁止空白 Issue + 课程官网/提问规范链接
│       ├── course-question.yaml      课程内容 / 知识点答疑
│       ├── homework-help.yaml        编程作业问题
│       └── env-setup.yaml            环境配置问题
└── homework/                         hwXX 作业仓库使用
    └── .gitea/ISSUE_TEMPLATE/
        ├── config.yaml               禁止空白 Issue + 引导到 general + 课程官网链接
        └── homework-help.yaml        编程作业问题(无作业编号字段)

config.yaml 里的链接与占位符

config.yaml 的 contact_links 是「新建 Issue」页面上的引导入口, 目前指向课程官网 (学会提问 / 课程信息 / 常见问题), 把答疑平台和官网串起来。课程官网地址是硬编码常量 (https://cpp.tongji.sh/Website/), 换域名时两个 config.yaml 要一起改。

平台自身的链接用占位符, 避免把学期组织名写死:

占位符 替换为 来源
{{BASE_URL}} 面向同学的平台地址 scripts/settings.toml 的 gitea.public_url
{{ORG}} 组织名(如 tjhlp-2025f) 推送时的目标仓库
{{REPO}} 仓库名(如 hw01) 推送时的目标仓库

换学期只要新建组织、重跑 setup init / create-homework, 模板里的链接会自动跟着走。 public_url 没配时会保留占位符并打印警告, 不会推上一条坏链接。 注意 gitea.url(CLI 调 API 用, 带内部端口)与 public_url(Apache 反代后的对外地址) 是两回事, 写进模板的必须是后者。

模板说明

general 仓库(3 个模板)

课程内容 / 知识点答疑 (course-question.yaml)

适用于 C/C++ 语法、数据结构、算法等课程内容的概念性疑问。

字段 类型 必填 说明
问题分类 dropdown Y 语法 / 数据类型 / 指针与内存 / 函数 / 结构体 / 文件操作 / 预处理 / 其他
问题描述 textarea Y 清晰描述问题
你目前的理解 textarea Y 描述当前理解和困惑点
参考资料 textarea N 已查阅的教材/网络资源
提交确认 checkboxes Y 已搜索重复 + 已查阅教材

编程作业问题 (homework-help.yaml)

适用于作业中遇到的编译错误、运行时错误、逻辑问题。

字段 类型 必填 说明
作业编号 input Y 如 "hw03 第2题"
问题类型 dropdown Y 编译错误 / 运行时错误 / 逻辑错误 / 思路不清晰 / 其他
问题描述 textarea Y
相关代码 textarea (render: c) Y 代码片段, 自动语法高亮
错误信息 / 实际输出 textarea (render: shell) N
期望行为 textarea Y
已尝试的调试方法 textarea Y 核心引导字段
提交确认 checkboxes Y 已搜索重复 + 仅贴相关代码

环境配置问题 (env-setup.yaml)

适用于 IDE 安装、编译器配置、开发环境搭建问题。课程统一使用 Windows。

字段 类型 必填 说明
IDE / 编辑器 dropdown Y Visual Studio / VS Code / CLion / Dev-C++ / Code::Blocks / 其他
编译器 dropdown Y MSVC / GCC (MinGW) / Clang / 不确定 / 其他
问题描述 textarea Y
已尝试的解决方法 textarea Y 核心引导字段
错误截图 / 日志 textarea N 支持拖拽上传图片
提交确认 checkboxes Y 已搜索重复 + 已查阅配置指南

homework 仓库(1 个模板)

作业仓库仅包含 homework-help.yaml, 与 general 版本的区别:

  • 无"作业编号"字段 - 仓库名(hw01, hw02...)本身即标识作业
  • 新增"题目理解"问题类型 - dropdown 中增加此选项
  • config.yaml 中引导非作业问题到 general 仓库

部署方式

模板通过 Python CLI 工具推送到仓库:

# 初始化时自动推送到 general 仓库
uv run tjhlp setup init --org tjhlp-2025f

# 创建作业仓库时自动推送作业模板
uv run tjhlp repos create-homework --org tjhlp-2025f --number 1

# 手动推送到指定仓库
uv run tjhlp repos init-templates tjhlp-2025f/general --type general
uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework

自定义

如需调整模板内容(如添加新的问题分类、修改引导文案、更新 config.yaml 里的链接), 直接编辑对应的 YAML 文件, 然后重新推送:

# 已有仓库原地更新(general 与各 hwNN 都要推一次)
uv run tjhlp repos init-templates tjhlp-2025f/general --type general
uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework

推送会覆盖远端同名文件(走 API 的 create-or-update), 不需要重建仓库。

YAML 模板语法参考 Gitea 文档。