mirror of
https://github.com/kvcache-ai/ktransformers.git
synced 2026-04-20 14:29:22 +00:00
aef6672dd8
* [feat]: update kt-kernel hooks and add contribution guide * [docs]: add contributing guide * [style]: format the python file and cpp file in kt-kernel
140 lines
3.8 KiB
Markdown
140 lines
3.8 KiB
Markdown
## Before Commit!
|
||
|
||
Your commit message must follow Conventional Commits (https://www.conventionalcommits.org/) and your code should be formatted. The Git hooks will do most of the work automatically:
|
||
|
||
### Tool Requirements
|
||
|
||
You need a recent `clang-format` (>= 18). In a conda environment you can install:
|
||
|
||
```shell
|
||
conda install -c conda-forge clang-format=18
|
||
```
|
||
|
||
If you previously configured with an older version, remove the build directory and reconfigure:
|
||
|
||
```shell
|
||
rm -rf kt-kernel/build
|
||
```
|
||
|
||
Install `black` for Python formatting:
|
||
|
||
```shell
|
||
conda install black
|
||
```
|
||
|
||
### Install hook:
|
||
```shell
|
||
bash kt-kernel/scripts/install-git-hooks.sh
|
||
#or just cmake the kt-kernel
|
||
cmake -S kt-kernel -B kt-kernel/build
|
||
```
|
||
|
||
There are manual commands if you need format.
|
||
|
||
```shell
|
||
cmake -S kt-kernel -B kt-kernel/build
|
||
cmake --build kt-kernel/build --target format
|
||
```
|
||
|
||
## Developer Note
|
||
|
||
Formatting and commit message rules are enforced by Git hooks. After installing `clang-format` and `black`, just commit normally—the hooks will run formatting for you.
|
||
|
||
> [!NOTE]
|
||
> If formatting modifies files, the commit is aborted after staging those changes. Review them and run `git commit` again. Repeat until no further formatting changes appear.
|
||
|
||
---
|
||
|
||
### Conventional Commit Regex (Reference)
|
||
|
||
The commit-msg hook enforces this pattern:
|
||
|
||
```text
|
||
regex='^\[(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip)\](\([^\)]+\))?(!)?: .+'
|
||
```
|
||
|
||
Meaning (English):
|
||
* `[type]` required — one of feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip
|
||
* Optional scope: `(scope)` — any chars except `)`
|
||
* Optional breaking change marker: `!` right after type or scope
|
||
* Separator: `: ` (colon + space)
|
||
* Subject: free text (at least one character)
|
||
|
||
Examples:
|
||
```text
|
||
[feat]: add adaptive batching
|
||
[fix(parser)]: handle empty token list
|
||
[docs]!: update API section for breaking rename
|
||
```
|
||
|
||
You can bypass locally (not recommended) with:
|
||
```shell
|
||
git commit --no-verify
|
||
```
|
||
## 提交前提醒
|
||
|
||
提交信息必须满足 Conventional Commits 规范 (https://www.conventionalcommits.org/)，代码需要符合格式要求。Git 钩子已经集成了大部分工作：
|
||
### 软件要求
|
||
|
||
需要较新的 `clang-format` (>= 18)，在 conda 环境中安装：
|
||
|
||
```shell
|
||
conda install -c conda-forge clang-format=18
|
||
```
|
||
|
||
如果之前用老版本配置过，请删除构建目录重新配置：
|
||
|
||
```shell
|
||
rm -rf kt-kernel/build
|
||
```
|
||
|
||
安装 `black` 以进行 Python 文件格式化：
|
||
|
||
```shell
|
||
conda install black
|
||
```
|
||
### 安装钩子
|
||
```shell
|
||
bash kt-kernel/scripts/install-git-hooks.sh
|
||
#or just cmake the kt-kernel
|
||
cmake -S kt-kernel -B kt-kernel/build
|
||
```
|
||
如果你需要手动格式化：
|
||
```shell
|
||
cmake -S kt-kernel -B kt-kernel/build
|
||
cmake --build kt-kernel/build --target format
|
||
```
|
||
|
||
## 开发者说明
|
||
|
||
本仓库通过 Git hooks 自动执行代码格式化与提交信息规范检查。只需安装好 `clang-format` 与 `black` 后正常执行提交即可，钩子会自动格式化。
|
||
|
||
> [!NOTE]
|
||
> 如果格式化修改了文件，钩子会终止提交并已暂存这些改动。请查看修改后再次执行 `git commit`，重复直到没有新的格式化变更。
|
||
|
||
### 提交信息正则（参考）
|
||
|
||
钩子使用如下正则检查提交信息：
|
||
```text
|
||
regex='^\[(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip)\](\([^\)]+\))?(!)?: .+'
|
||
```
|
||
含义：
|
||
* `[type]` 必填：feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip
|
||
* 作用域可选：`(scope)`，不能包含右括号
|
||
* 可选的破坏性标记：`!`
|
||
* 分隔符：冒号+空格 `: `
|
||
* 描述：至少一个字符
|
||
|
||
示例：
|
||
```text
|
||
[feat]: 增加自适应 batch 功能
|
||
[fix(tokenizer)]: 修复空 token 列表处理
|
||
[docs]!: 更新接口文档（存在破坏性修改）
|
||
```
|
||
|
||
跳过钩子（不推荐，仅紧急时）：
|
||
```shell
|
||
git commit --no-verify
|
||
```
|
||
|