Skip to content

FreeToken brings datacenter-scale model serving to your desktop. Run massive models locally, fast and efficiently.

chore: add issue templates with FAQ/Roadmap checks and auto-labels (#375)

Xiaoze Fan86214a944e87
diff --git a/.github/ISSUE_TEMPLATE/bug_desktop.yml b/.github/ISSUE_TEMPLATE/bug_desktop.yml
new file mode 100644
index 00000000..6adfd875
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_desktop.yml
@@ -0,0 +1,93 @@
+name: Bug report (Desktop app)
+description: Something does not work in the FreeToken Desktop app.
+labels: ["bug", "Desktop"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Before opening an issue, please read the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84) and the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79). Most install and runtime problems are answered in the FAQ. Reports missing the information below may be closed until it is provided; see [CONTRIBUTING.md](https://github.com/FlashML-org/FreeToken/blob/main/CONTRIBUTING.md#reporting-issues).
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Before you start
+ options:
+ - label: I have read the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84) and my problem is not answered there.
+ required: true
+ - label: I have read the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79) and this is not already planned there.
+ required: true
+ - label: I have searched [existing issues](https://github.com/FlashML-org/FreeToken/issues?q=is%3Aissue) and found no duplicate.
+ required: true
+ - label: I have restarted the Desktop app to pick up the latest update and the problem still happens.
+ required: true
+ - type: textarea
+ id: description
+ attributes:
+ label: What happened
+ description: What you did, what you expected, and what happened instead.
+ validations:
+ required: true
+ - type: input
+ id: version
+ attributes:
+ label: Desktop app version
+ description: Shown in the app's settings / about page.
+ validations:
+ required: true
+ - type: dropdown
+ id: os
+ attributes:
+ label: OS
+ options:
+ - Windows 11
+ - Windows 10
+ - Ubuntu
+ - Debian
+ - Fedora
+ - Arch Linux
+ - Other Linux
+ validations:
+ required: true
+ - type: input
+ id: os_detail
+ attributes:
+ label: OS details
+ description: Distribution version (e.g. Ubuntu 24.04), kernel, desktop environment, or anything unusual about the system.
+ - type: input
+ id: gpu
+ attributes:
+ label: GPU and driver
+ description: "GPU model, VRAM, driver version (`nvidia-smi`). Mention other GPUs in the machine. Only NVIDIA GPUs are supported today; AMD support is on the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79), please do not open an issue for it."
+ placeholder: RTX 4060 Laptop 8GB, driver 580.xx
+ validations:
+ required: true
+ - type: input
+ id: cpu
+ attributes:
+ label: CPU and system RAM
+ placeholder: i9-13900H, 32GB
+ validations:
+ required: true
+ - type: input
+ id: model
+ attributes:
+ label: Checkpoint
+ description: The exact Hugging Face or ModelScope ID, not just the model name.
+ placeholder: Qwen/Qwen3.6-35B-A3B-FP8
+ validations:
+ required: true
+ - type: textarea
+ id: settings
+ attributes:
+ label: Model settings
+ description: The settings used when loading the model (context length, backend, any changed defaults).
+ - type: textarea
+ id: log
+ attributes:
+ label: Engine log
+ description: "**Logs → Server status → Copy** in the app, pasted as text, not a screenshot."
+ render: text
+ - type: textarea
+ id: extra
+ attributes:
+ label: Anything else
+ description: Proxies, unusual setups, or anything that may matter.
diff --git a/.github/ISSUE_TEMPLATE/bug_engine.yml b/.github/ISSUE_TEMPLATE/bug_engine.yml
new file mode 100644
index 00000000..b29bf768
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_engine.yml
@@ -0,0 +1,105 @@
+name: Bug report (Engine)
+description: Something does not work with the FreeToken engine (ft command line, pip wheel, or source build).
+labels: ["bug"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Before opening an issue, please read the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84) and the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79). Most install and runtime problems are answered in the FAQ. Reports missing the information below may be closed until it is provided; see [CONTRIBUTING.md](https://github.com/FlashML-org/FreeToken/blob/main/CONTRIBUTING.md#reporting-issues).
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Before you start
+ options:
+ - label: I have read the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84) and my problem is not answered there.
+ required: true
+ - label: I have read the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79) and this is not already planned there.
+ required: true
+ - label: I have searched [existing issues](https://github.com/FlashML-org/FreeToken/issues?q=is%3Aissue) and found no duplicate.
+ required: true
+ - label: I am on the latest release, or on a freshly rebuilt `main` when building from source.
+ required: true
+ - type: textarea
+ id: description
+ attributes:
+ label: What happened
+ description: What you did, what you expected, and what happened instead.
+ validations:
+ required: true
+ - type: dropdown
+ id: install
+ attributes:
+ label: How did you install FreeToken
+ options:
+ - pip / uv wheel
+ - Built from source
+ validations:
+ required: true
+ - type: input
+ id: version
+ attributes:
+ label: FreeToken version
+ description: "`ft --version`, or `git rev-parse --short HEAD` when building from source."
+ validations:
+ required: true
+ - type: dropdown
+ id: os
+ attributes:
+ label: OS
+ options:
+ - Windows 11
+ - Windows 10
+ - WSL2 on Windows 11
+ - WSL2 on Windows 10
+ - Ubuntu
+ - Debian
+ - Fedora
+ - Arch Linux
+ - Other Linux
+ validations:
+ required: true
+ - type: input
+ id: os_detail
+ attributes:
+ label: OS details
+ description: Distribution version (e.g. Ubuntu 24.04), kernel, WSL distro, Python version, or anything unusual about the system.
+ - type: input
+ id: gpu
+ attributes:
+ label: GPU and driver
+ description: "GPU model, VRAM, driver version (`nvidia-smi`). Mention other GPUs in the machine. Only NVIDIA GPUs are supported today; AMD support is on the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79), please do not open an issue for it."
+ placeholder: RTX 4060 Laptop 8GB, driver 580.xx
+ validations:
+ required: true
+ - type: input
+ id: cpu
+ attributes:
+ label: CPU and system RAM
+ placeholder: i9-13900H, 32GB
+ validations:
+ required: true
+ - type: input
+ id: model
+ attributes:
+ label: Checkpoint
+ description: The exact Hugging Face or ModelScope ID, not just the model name.
+ placeholder: Qwen/Qwen3.6-35B-A3B-FP8
+ validations:
+ required: true
+ - type: textarea
+ id: command
+ attributes:
+ label: Command
+ description: The exact command you ran.
+ render: shell
+ - type: textarea
+ id: log
+ attributes:
+ label: Full log
+ description: The full log as text, not a screenshot of the last line.
+ render: text
+ - type: textarea
+ id: extra
+ attributes:
+ label: Anything else
+ description: Proxies, unusual setups, or anything that may matter.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 00000000..c3517a9e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,17 @@
+blank_issues_enabled: false
+contact_links:
+ - name: FAQ (read first)
+ url: https://github.com/FlashML-org/FreeToken/issues/84
+ about: Most install and runtime problems are already answered here.
+ - name: Roadmap (read first)
+ url: https://github.com/FlashML-org/FreeToken/issues/79
+ about: What we are working on next. Please do not open a new issue for something already on the Roadmap.
+ - name: Usage questions (Discord)
+ url: https://discord.gg/MsA277cJzZ
+ about: Ask on the Community Discord instead of opening an issue.
+ - name: Usage questions (WeChat, CN)
+ url: https://github.com/FlashML-org/FreeToken/blob/main/assets/freetoken-wechatgroup.png
+ about: Scan the QR code to join the Community WeChat group.
+ - name: Development discussion
+ url: https://join.slack.com/t/flashml/shared_invite/zt-3zpdh5j10-9dwTXrgLiqpVxizhA9KVbA
+ about: Join the Developer Slack to discuss Roadmap items before starting work.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 00000000..131c9f42
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,46 @@
+name: Feature request
+description: Suggest a feature or improvement. For a model or checkpoint that does not load, use "Support Model Checkpoint" instead.
+labels: ["feature"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Before opening an issue, please check the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79) and the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84). If your request is already on the Roadmap, please do not open a new issue for it. Features not on the Roadmap should start as an issue, not a PR; see [CONTRIBUTING.md](https://github.com/FlashML-org/FreeToken/blob/main/CONTRIBUTING.md).
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Before you start
+ options:
+ - label: I have read the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79) and this is not already planned there.
+ required: true
+ - label: I have read the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84).
+ required: true
+ - label: I have searched [existing issues](https://github.com/FlashML-org/FreeToken/issues?q=is%3Aissue) and found no duplicate.
+ required: true
+ - type: dropdown
+ id: target
+ attributes:
+ label: Applies to
+ options:
+ - Desktop app
+ - Engine
+ - Both
+ validations:
+ required: true
+ - type: textarea
+ id: problem
+ attributes:
+ label: What problem does this solve
+ description: The use case, and why current FreeToken does not cover it.
+ validations:
+ required: true
+ - type: textarea
+ id: proposal
+ attributes:
+ label: Proposed solution
+ validations:
+ required: true
+ - type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives considered
diff --git a/.github/ISSUE_TEMPLATE/model_checkpoint.yml b/.github/ISSUE_TEMPLATE/model_checkpoint.yml
new file mode 100644
index 00000000..77f11ffa
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/model_checkpoint.yml
@@ -0,0 +1,66 @@
+name: Support Model Checkpoint
+description: A checkpoint FreeToken cannot load, whether a new model architecture or an unsupported checkpoint or quantization of a supported one.
+labels: ["new-model"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Before opening an issue, please check the [supported models](https://github.com/FlashML-org/FreeToken/blob/main/docs/models.md), the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79) and the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84). A checkpoint listed there that fails to load is a bug: use a Bug report instead. Other checkpoints of a supported architecture usually work without changes; try them first. If the architecture is supported but a specific unlisted checkpoint or quantization fails to load, this is the right template.
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Before you start
+ options:
+ - label: I have checked the [supported models](https://github.com/FlashML-org/FreeToken/blob/main/docs/models.md) and this checkpoint is not listed there. A listed checkpoint that fails is a bug; use a Bug report instead.
+ required: true
+ - label: I have read the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79) and this model is not already planned there.
+ required: true
+ - label: I have read the [FAQ](https://github.com/FlashML-org/FreeToken/issues/84).
+ required: true
+ - label: I have searched [existing issues](https://github.com/FlashML-org/FreeToken/issues?q=is%3Aissue) and found no duplicate.
+ required: true
+ - label: This is not a GGUF checkpoint. GGUF support is on the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79); please do not open an issue for it.
+ required: true
+ - type: input
+ id: link
+ attributes:
+ label: Hugging Face link
+ description: The exact checkpoint you want to run, not just the model family.
+ placeholder: https://huggingface.co/Qwen/Qwen3.6-35B-A3B-FP8
+ validations:
+ required: true
+ - type: dropdown
+ id: arch
+ attributes:
+ label: Is the model architecture already supported
+ description: Check the architecture, not the checkpoint, against the [supported models](https://github.com/FlashML-org/FreeToken/blob/main/docs/models.md) table.
+ options:
+ - Yes, but this checkpoint or quantization does not load
+ - No, this is a new model architecture
+ - Not sure
+ validations:
+ required: true
+ - type: dropdown
+ id: quant
+ attributes:
+ label: Is the quantization already supported
+ description: FP8, NVFP4 and MXFP4 are supported today.
+ options:
+ - Not quantized
+ - Yes, but this checkpoint's weight format does not load
+ - No, a new quantization
+ - GGUF (on the Roadmap, please do not open an issue)
+ - Not sure
+ validations:
+ required: true
+ - type: textarea
+ id: log
+ attributes:
+ label: What happens when you load it
+ description: The error or log from trying to load the checkpoint, as text. Leave empty if you have not tried.
+ render: text
+ - type: textarea
+ id: extra
+ attributes:
+ label: Anything else
+ description: Links to other engines that support it, or anything that may matter.
diff --git a/.github/issue-labeler.yml b/.github/issue-labeler.yml
new file mode 100644
index 00000000..8d51b626
--- /dev/null
+++ b/.github/issue-labeler.yml
@@ -0,0 +1,14 @@
+windows:
+ - '### OS\s+Windows 1[01]'
+WSL:
+ - '### OS\s+WSL2'
+linux:
+ - '### OS\s+(Ubuntu|Debian|Fedora|Arch Linux|Other Linux)'
+amd:
+ - '### GPU and driver\s+[^\n]*(AMD|Radeon|ROCm)'
+Desktop:
+ - '### Applies to\s+(Desktop app|Both)'
+gguf:
+ - '### Is the quantization already supported\s+GGUF'
+quant:
+ - '### Is the quantization already supported\s+No,'
diff --git a/.github/workflows/issue-labels.yml b/.github/workflows/issue-labels.yml
new file mode 100644
index 00000000..35f325bf
--- /dev/null
+++ b/.github/workflows/issue-labels.yml
@@ -0,0 +1,30 @@
+name: Label issues
+
+on:
+ issues:
+ types: [opened, edited]
+
+permissions:
+ issues: write
+
+jobs:
+ label:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: github/[email protected]
+ with:
+ configuration-path: .github/issue-labeler.yml
+ enable-versioned-regex: 0
+ include-title: 0
+ repo-token: ${{ github.token }}
+ - if: github.event.action == 'opened'
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const body = context.payload.issue.body || '';
+ if (!/### Is the quantization already supported\s+GGUF/.test(body)) return;
+ await github.rest.issues.createComment({
+ ...context.repo,
+ issue_number: context.issue.number,
+ body: 'Thanks for the request. General GGUF support is tracked on the [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79) and is not taken as a separate issue yet. Please follow the Roadmap for progress, or comment there with the checkpoint you need. Note that FreeToken loads Hugging Face safetensors checkpoints directly, so an FP8 / NVFP4 / BF16 version of the same model may already work; see [supported models](https://github.com/FlashML-org/FreeToken/blob/main/docs/models.md).',
+ });
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e286808d..62461d43 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,7 +6,7 @@ Thanks for helping make FreeToken better. This page covers how to report issues
- [FAQ](https://github.com/FlashML-org/FreeToken/issues/84): kept up to date; most install and runtime problems are answered there.
- [Roadmap](https://github.com/FlashML-org/FreeToken/issues/79): what we are working on next.
-- [Developer Slack](https://join.slack.com/t/flashml/shared_invite/zt-3zpdh5j10-9dwTXrgLiqpVxizhA9KVbA) for development discussion; [Community Discord](https://discord.gg/xzwSnMdsX) or [Community WeChat](https://github.com/FlashML-org/FreeToken/blob/main/assets/freetoken-wechatgroup.png) for usage questions.
+- [Developer Slack](https://join.slack.com/t/flashml/shared_invite/zt-3zpdh5j10-9dwTXrgLiqpVxizhA9KVbA) for development discussion; [Community Discord](https://discord.gg/MsA277cJzZ) or [Community WeChat](https://github.com/FlashML-org/FreeToken/blob/main/assets/freetoken-wechatgroup.png) for usage questions.
## Reporting issues