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.ymlnew file mode 100644index 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.ymlnew file mode 100644index 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.ymlnew file mode 100644index 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.ymlnew file mode 100644index 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 considereddiff --git a/.github/ISSUE_TEMPLATE/model_checkpoint.yml b/.github/ISSUE_TEMPLATE/model_checkpoint.ymlnew file mode 100644index 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.ymlnew file mode 100644index 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.ymlnew file mode 100644index 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.mdindex 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