GitHub Issues

issue 跟踪器用于已确认的缺陷和具体的功能请求——也就是维护者（或您）原则上可以通过编写代码来处理的事项。开放式的问题、设计讨论以及"我该如何做 X"之类的内容则应放到 GitHub Discussions 或 Discord；新建 issue 的选择器会在模板之外一并提供这些途径。

提交 issue

File a new issue  →    open issues

点击上方链接会进入新建 issue 选择器——这是一个菜单，包含两个模板和三个"您可能想去别处"的快捷入口：

选项

何时选择它

🐛 Bug Report

某处出现故障或错误，并且您能够复现它。

✨ Feature Request

您希望增加或更改某项具体、范围明确的内容。

💬 使用问题

重定向至 Discussions Q&A——而非 issue。

💡 想法或提案

重定向至 Discussions Ideas & RFCs——而非 issue。

🗨️ 实时交流

重定向至 Discord。

已禁用空白 issue——每个 issue 都从模板开始，这样可以让分类整理保持井然有序。

每个模板收集哪些信息

两个模板都是 GitHub 的 issue 表单：带有校验的结构化字段，以表单形式而非自由的 Markdown 形式呈现。必填字段都有清晰标注。

🐛 Bug Report——必填字段为 Description（描述）、Minimal reproducing example（最小复现示例）、Expected behavior（期望行为）、Environment（环境），外加两个提交前的勾选项。完整的回溯信息是可选的（有些缺陷产生的是错误结果而非异常）。环境字段会明确告诉您应粘贴哪些内容：

python -c "import torch, torch_sla, tensormesh, platform; \
  print('torch:      ', torch.__version__); \
  print('torch_sla:  ', torch_sla.__version__); \
  print('tensormesh: ', tensormesh.__version__); \
  print('python:     ', platform.python_version()); \
  print('os:         ', platform.platform()); \
  print('cuda:       ', torch.version.cuda if torch.cuda.is_available() else 'n/a')"

如果您填不出 Minimal reproducing example，这通常意味着问题还没有被充分简化——请在提交前尝试将其缩小。一个 200 行的脚本和一个五行的脚本，让人阅读时所需的精力大致相同，而五行的脚本得到快速答复的可能性要高出十倍。

✨ Feature Request——只有 Use case（用例）是严格必填的。请以动机（"我想要解决 X"）作为开头，而不是预设的 API（"请添加 foo"）。清晰的用例能让维护者和社区一同塑造 API；而预先指定的 API 往往会把讨论锚定在错误的方向上。

提交之后会发生什么

基本流程如下：

  1. 自动打标签——每个新 issue 都会带有 triage 标签，以及由模板设定的类别标签（bug 或 enhancement）。

  2. 分类整理——维护者会阅读它，可能会要求补充更多信息，在报告变得可处理后移除 triage 标签，并添加主题标签（例如 meshing、solver、cuda），以便相似的 issue 聚集在一起。

  3. 处置结果——为以下之一：

    • 已确认并排入待处理队列（会有人来接手；也欢迎您自己来处理——参见 贡献指南）。

    • 要求进一步澄清（请予以回复；长期无人跟进的陈旧 issue 可能会被关闭）。

    • 因重复、无效或"不予修复"而关闭，并附上说明。

这是一个隶属于科研机构的项目，维护团队规模很小——响应时间为尽力而为，并非合同义务。如果您的 issue 因论文截止日期而紧急，请在描述中说明；如果它沉寂了两周以上，欢迎礼貌地提醒一下。

提交之前：请先搜索

花 30 秒搜索一下，就能避免大多数重复，而且往往能找到现成的变通办法。有用的入口：

  • 限定在本仓库范围内、包含未关闭与已关闭的 issue：https://github.com/camlab-ethz/TensorMesh/issues?q=<terms>（去掉默认的 is:open 即可一并包含已关闭的 issue）。

  • Discussions——使用问题和设计讨论位于那里，而非这里。

  • 使用带 site: 过滤器的 Google 搜索：site:github.com/camlab-ethz/TensorMesh <your terms>。

如果您找到一个相关的 issue，但您的问题确实有所不同，请在您的新 issue 中关联它（"与 #NN 相关，但 X 不同"）——这有助于分类整理时判断是否应将它们合并。

从 Discussion 到 Issue

Issue 和 Discussion 会在两个自然的方向上相互转化：

  • Q&A → Bug。 Discussions 问答区里一个"我该如何……"的问题最终被证实是一个真正的缺陷。请提交一个 issue，引用该讨论帖以提供背景（Discussion: #DD），并从讨论帖中反向链接到该 issue。不要把整段对话再粘贴一遍。

  • Idea & RFC → Feature。 当一场设计讨论达成共识后，提交一个 issue（或一个 PR），在描述中写明商定的设计，并链接到该讨论帖。此时 issue 即是正式承诺，而讨论则是审议过程。

拉取请求

本页讲的是提交 issue。如果您想修复某个 issue，PR 的工作流程——开发环境、分支命名、测试、文档更新——都在 贡献指南 中。将 PR 关联到对应的 issue（在描述中写 Fixes #NN）会在合并时自动关闭该 issue，而上文的分类整理流程正依赖于这一点。