SHA256
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() 及单元测试
This commit is contained in:
@@ -17,16 +17,35 @@
|
|||||||
issue-templates/
|
issue-templates/
|
||||||
├── general/ general 仓库使用
|
├── general/ general 仓库使用
|
||||||
│ └── .gitea/ISSUE_TEMPLATE/
|
│ └── .gitea/ISSUE_TEMPLATE/
|
||||||
│ ├── config.yaml 禁止空白 Issue + 外部链接
|
│ ├── config.yaml 禁止空白 Issue + 课程官网/提问规范链接
|
||||||
│ ├── course-question.yaml 课程内容 / 知识点答疑
|
│ ├── course-question.yaml 课程内容 / 知识点答疑
|
||||||
│ ├── homework-help.yaml 编程作业问题
|
│ ├── homework-help.yaml 编程作业问题
|
||||||
│ └── env-setup.yaml 环境配置问题
|
│ └── env-setup.yaml 环境配置问题
|
||||||
└── homework/ hwXX 作业仓库使用
|
└── homework/ hwXX 作业仓库使用
|
||||||
└── .gitea/ISSUE_TEMPLATE/
|
└── .gitea/ISSUE_TEMPLATE/
|
||||||
├── config.yaml 禁止空白 Issue + 引导到 general
|
├── config.yaml 禁止空白 Issue + 引导到 general + 课程官网链接
|
||||||
└── homework-help.yaml 编程作业问题(无作业编号字段)
|
└── 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 个模板)
|
### general 仓库(3 个模板)
|
||||||
@@ -97,10 +116,15 @@ uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework
|
|||||||
|
|
||||||
## 自定义
|
## 自定义
|
||||||
|
|
||||||
如需调整模板内容(如添加新的问题分类、修改引导文案), 直接编辑对应的 YAML 文件, 然后重新推送:
|
如需调整模板内容(如添加新的问题分类、修改引导文案、更新 `config.yaml` 里的链接),
|
||||||
|
直接编辑对应的 YAML 文件, 然后重新推送:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# 已有仓库原地更新(general 与各 hwNN 都要推一次)
|
||||||
uv run tjhlp repos init-templates tjhlp-2025f/general --type general
|
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 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。
|
YAML 模板语法参考 [Gitea 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。
|
||||||
|
|||||||
@@ -1,8 +1,11 @@
|
|||||||
blank_issues_enabled: false
|
blank_issues_enabled: false
|
||||||
contact_links:
|
contact_links:
|
||||||
- name: 课程主页
|
- name: 提问前必读 · 学会提问
|
||||||
url: https://example.com
|
url: http://10.80.42.185/Website/ask-question/
|
||||||
about: 访问课程主页获取有关资源
|
about: 课程官网上的提问规范。不合规范的提问很可能不会得到回答
|
||||||
- name: 常见问题汇总
|
- name: 课程官网
|
||||||
url: https://example.com/faq
|
url: http://10.80.42.185/Website/
|
||||||
about: 提问前请先查阅常见问题汇总
|
about: 课程信息、作业说明、环境配置要求、常见问题
|
||||||
|
- name: 答疑平台提问指南
|
||||||
|
url: "{{BASE_URL}}/assets/tjhlp/ask-guide.html"
|
||||||
|
about: 搜索 Issue、选择模板、填写信息、关闭 Issue 的平台内速查
|
||||||
|
|||||||
@@ -1,5 +1,11 @@
|
|||||||
blank_issues_enabled: false
|
blank_issues_enabled: false
|
||||||
contact_links:
|
contact_links:
|
||||||
- name: 一般性问题请到 general 仓库提问
|
- name: 一般性问题请到 general 仓库提问
|
||||||
url: https://example.com
|
url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose"
|
||||||
about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库
|
about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库
|
||||||
|
- name: 提问前必读 · 学会提问
|
||||||
|
url: https://cpp.tongji.sh/Website/ask-question/
|
||||||
|
about: 课程官网上的提问规范。不合规范的提问很可能不会得到回答
|
||||||
|
- name: 课程官网
|
||||||
|
url: https://cpp.tongji.sh/Website/
|
||||||
|
about: 课程信息、作业说明、环境配置要求、常见问题
|
||||||
|
|||||||
@@ -1,5 +1,8 @@
|
|||||||
[default.gitea]
|
[default.gitea]
|
||||||
url = "https://cpp.tongji.sh:3000"
|
url = "https://cpp.tongji.sh:3000"
|
||||||
|
# 同学实际访问的平台地址(Apache 反代 /QA -> 127.0.0.1:2080)。
|
||||||
|
# 用于 Issue Template 等面向用户的链接; url 只用于 CLI 调 API。
|
||||||
|
public_url = "https://cpp.tongji.sh/QA"
|
||||||
email_domain = "tongji.edu.cn"
|
email_domain = "tongji.edu.cn"
|
||||||
default_org = ""
|
default_org = ""
|
||||||
|
|
||||||
|
|||||||
@@ -9,7 +9,7 @@ from rich.console import Console
|
|||||||
|
|
||||||
from tjhlp.client import GiteaClient, GiteaClientError
|
from tjhlp.client import GiteaClient, GiteaClientError
|
||||||
from tjhlp.config import get_gitea_config
|
from tjhlp.config import get_gitea_config
|
||||||
from tjhlp.utils import parse_repo, push_templates, sync_labels
|
from tjhlp.utils import parse_repo, push_templates, sync_labels, web_base_url
|
||||||
|
|
||||||
app = typer.Typer(no_args_is_help=True)
|
app = typer.Typer(no_args_is_help=True)
|
||||||
console = Console()
|
console = Console()
|
||||||
@@ -69,7 +69,7 @@ def create_homework(
|
|||||||
# 推送作业 Issue Templates
|
# 推送作业 Issue Templates
|
||||||
console.print("\n推送 Issue Templates...")
|
console.print("\n推送 Issue Templates...")
|
||||||
hw_tpl_dir = _TEMPLATES_DIR / "homework"
|
hw_tpl_dir = _TEMPLATES_DIR / "homework"
|
||||||
n = push_templates(client, org, repo_name, hw_tpl_dir)
|
n = push_templates(client, org, repo_name, hw_tpl_dir, web_base_url(cfg))
|
||||||
console.print(f" 共推送 {n} 个模板文件")
|
console.print(f" 共推送 {n} 个模板文件")
|
||||||
|
|
||||||
# 同步 Labels
|
# 同步 Labels
|
||||||
@@ -120,7 +120,7 @@ def init_templates(
|
|||||||
|
|
||||||
cfg = get_gitea_config()
|
cfg = get_gitea_config()
|
||||||
with GiteaClient(cfg) as client:
|
with GiteaClient(cfg) as client:
|
||||||
n = push_templates(client, org_name, repo_name, tpl_dir)
|
n = push_templates(client, org_name, repo_name, tpl_dir, web_base_url(cfg))
|
||||||
console.print(f"\n共推送 {n} 个模板文件到 {repo}")
|
console.print(f"\n共推送 {n} 个模板文件到 {repo}")
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -9,7 +9,7 @@ from rich.console import Console
|
|||||||
|
|
||||||
from tjhlp.client import GiteaClient, GiteaClientError
|
from tjhlp.client import GiteaClient, GiteaClientError
|
||||||
from tjhlp.config import get_gitea_config
|
from tjhlp.config import get_gitea_config
|
||||||
from tjhlp.utils import push_templates, sync_labels
|
from tjhlp.utils import push_templates, sync_labels, web_base_url
|
||||||
|
|
||||||
app = typer.Typer(no_args_is_help=True)
|
app = typer.Typer(no_args_is_help=True)
|
||||||
console = Console()
|
console = Console()
|
||||||
@@ -86,7 +86,7 @@ def init(
|
|||||||
console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]")
|
console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]")
|
||||||
general_tpl_dir = _TEMPLATES_DIR / "general"
|
general_tpl_dir = _TEMPLATES_DIR / "general"
|
||||||
if general_tpl_dir.exists():
|
if general_tpl_dir.exists():
|
||||||
n = push_templates(client, org, "general", general_tpl_dir)
|
n = push_templates(client, org, "general", general_tpl_dir, web_base_url(cfg))
|
||||||
console.print(f" 共推送 {n} 个模板文件")
|
console.print(f" 共推送 {n} 个模板文件")
|
||||||
else:
|
else:
|
||||||
console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]")
|
console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]")
|
||||||
|
|||||||
@@ -55,6 +55,10 @@ class GiteaConfig(BaseModel):
|
|||||||
token: SecretStr
|
token: SecretStr
|
||||||
email_domain: str = "tongji.edu.cn"
|
email_domain: str = "tongji.edu.cn"
|
||||||
default_org: str = ""
|
default_org: str = ""
|
||||||
|
# 面向用户的访问地址(Apache 反代后的地址, 如 https://cpp.tongji.sh/QA)。
|
||||||
|
# url 是 CLI 调 API 用的地址, 可能带内部端口, 不能直接写进 Issue Template 等
|
||||||
|
# 给同学看的链接里; 留空时回退到 url。
|
||||||
|
public_url: str = ""
|
||||||
labels: list[LabelDef] = []
|
labels: list[LabelDef] = []
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -34,11 +34,38 @@ def parse_repo(repo: str) -> tuple[str, str]:
|
|||||||
# ---------------------------------------------------------------------------
|
# ---------------------------------------------------------------------------
|
||||||
# Issue Template 推送
|
# Issue Template 推送
|
||||||
# ---------------------------------------------------------------------------
|
# ---------------------------------------------------------------------------
|
||||||
|
# 模板占位符: 让 Issue Template 不必硬编码学期组织名/访问地址
|
||||||
|
# {{BASE_URL}} -> gitea.public_url(面向同学的地址)
|
||||||
|
# {{ORG}} / {{REPO}} -> 推送目标
|
||||||
|
TEMPLATE_PLACEHOLDERS = ("{{BASE_URL}}", "{{ORG}}", "{{REPO}}")
|
||||||
|
|
||||||
|
|
||||||
|
def web_base_url(cfg: GiteaConfig) -> str:
|
||||||
|
"""面向同学的平台访问地址: 优先 gitea.public_url, 否则退回 gitea.url。"""
|
||||||
|
return (cfg.public_url or str(cfg.url)).rstrip("/")
|
||||||
|
|
||||||
|
|
||||||
|
def render_template_placeholders(text: str, org: str, repo: str, web_base: str = "") -> str:
|
||||||
|
"""替换 Issue Template 中的占位符, 返回渲染后的文本。"""
|
||||||
|
base = (web_base or "").rstrip("/")
|
||||||
|
if base:
|
||||||
|
text = text.replace("{{BASE_URL}}", base)
|
||||||
|
text = text.replace("{{ORG}}", org).replace("{{REPO}}", repo)
|
||||||
|
left = [p for p in TEMPLATE_PLACEHOLDERS if p in text]
|
||||||
|
if left:
|
||||||
|
console.print(
|
||||||
|
f"[yellow]警告: 模板中仍有未替换的占位符 {', '.join(left)}"
|
||||||
|
f"(检查 settings.toml 的 gitea.public_url)[/yellow]"
|
||||||
|
)
|
||||||
|
return text
|
||||||
|
|
||||||
|
|
||||||
def push_templates(
|
def push_templates(
|
||||||
client: GiteaClient,
|
client: GiteaClient,
|
||||||
org: str,
|
org: str,
|
||||||
repo: str,
|
repo: str,
|
||||||
template_dir: Path,
|
template_dir: Path,
|
||||||
|
web_base: str = "",
|
||||||
) -> int:
|
) -> int:
|
||||||
"""将本地 issue template 目录推送到远端仓库, 返回推送的文件数。"""
|
"""将本地 issue template 目录推送到远端仓库, 返回推送的文件数。"""
|
||||||
count = 0
|
count = 0
|
||||||
@@ -51,7 +78,13 @@ def push_templates(
|
|||||||
if not filepath.is_file():
|
if not filepath.is_file():
|
||||||
continue
|
continue
|
||||||
remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}"
|
remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}"
|
||||||
content_b64 = base64.b64encode(filepath.read_bytes()).decode()
|
text = render_template_placeholders(
|
||||||
|
filepath.read_text(encoding="utf-8"),
|
||||||
|
org=org,
|
||||||
|
repo=repo,
|
||||||
|
web_base=web_base,
|
||||||
|
)
|
||||||
|
content_b64 = base64.b64encode(text.encode("utf-8")).decode()
|
||||||
|
|
||||||
existing = client.get_file_contents(org, repo, remote_path)
|
existing = client.get_file_contents(org, repo, remote_path)
|
||||||
if existing:
|
if existing:
|
||||||
|
|||||||
@@ -1,10 +1,17 @@
|
|||||||
"""utils.py 单元测试: parse_repo, compute_issue_stats"""
|
"""utils.py 单元测试: parse_repo, compute_issue_stats, render_template_placeholders"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import pytest
|
import pytest
|
||||||
|
from pydantic import SecretStr
|
||||||
|
|
||||||
from tjhlp.utils import compute_issue_stats, parse_repo
|
from tjhlp.config import GiteaConfig
|
||||||
|
from tjhlp.utils import (
|
||||||
|
compute_issue_stats,
|
||||||
|
parse_repo,
|
||||||
|
render_template_placeholders,
|
||||||
|
web_base_url,
|
||||||
|
)
|
||||||
|
|
||||||
# typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit
|
# typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit
|
||||||
_EXIT_EXCEPTIONS = (SystemExit, Exception)
|
_EXIT_EXCEPTIONS = (SystemExit, Exception)
|
||||||
@@ -103,3 +110,44 @@ class TestComputeIssueStats:
|
|||||||
]
|
]
|
||||||
stats = compute_issue_stats(issues)
|
stats = compute_issue_stats(issues)
|
||||||
assert stats["no_reply"] == 1
|
assert stats["no_reply"] == 1
|
||||||
|
|
||||||
|
|
||||||
|
class TestRenderTemplatePlaceholders:
|
||||||
|
def test_replaces_all_placeholders(self):
|
||||||
|
out = render_template_placeholders(
|
||||||
|
'url: "{{BASE_URL}}/{{ORG}}/{{REPO}}/issues"',
|
||||||
|
org="tjhlp-2025f",
|
||||||
|
repo="hw01",
|
||||||
|
web_base="https://cpp.tongji.sh/QA/",
|
||||||
|
)
|
||||||
|
assert out == 'url: "https://cpp.tongji.sh/QA/tjhlp-2025f/hw01/issues"'
|
||||||
|
|
||||||
|
def test_strips_trailing_slash_of_web_base(self):
|
||||||
|
out = render_template_placeholders(
|
||||||
|
"{{BASE_URL}}/assets/x.html", "org", "repo", "http://h/QA//"
|
||||||
|
)
|
||||||
|
assert out == "http://h/QA/assets/x.html"
|
||||||
|
|
||||||
|
def test_leaves_base_url_when_not_configured(self):
|
||||||
|
# public_url 没配时应保留占位符(由 push_templates 打警告), 而不是生成坏链接
|
||||||
|
out = render_template_placeholders("{{BASE_URL}}/x", "org", "repo")
|
||||||
|
assert "{{BASE_URL}}" in out
|
||||||
|
|
||||||
|
def test_text_without_placeholders_is_unchanged(self):
|
||||||
|
text = "blank_issues_enabled: false\n"
|
||||||
|
assert render_template_placeholders(text, "org", "repo", "http://h") == text
|
||||||
|
|
||||||
|
|
||||||
|
class TestWebBaseUrl:
|
||||||
|
def _cfg(self, **kw):
|
||||||
|
base = {"url": "https://cpp.tongji.sh:3000", "token": SecretStr("x")}
|
||||||
|
return GiteaConfig(**{**base, **kw})
|
||||||
|
|
||||||
|
def test_prefers_public_url(self):
|
||||||
|
assert (
|
||||||
|
web_base_url(self._cfg(public_url="https://cpp.tongji.sh/QA/"))
|
||||||
|
== "https://cpp.tongji.sh/QA"
|
||||||
|
)
|
||||||
|
|
||||||
|
def test_falls_back_to_url(self):
|
||||||
|
assert web_base_url(self._cfg()) == "https://cpp.tongji.sh:3000"
|
||||||
|
|||||||
Reference in New Issue
Block a user