# 开发规范

## 基本

### 版本控制

project X 的代码被托管在 github 上:

- xray 核心 [xray-core](https://github.com/XTLS/Xray-core)
- xray-flutter [xray-flutter](https://github.com/XTLS/Xray-flutter)
- 安装脚本 [Xray-install](https://github.com/XTLS/Xray-install)
- 数据文件 [Xray-rules-dat](https://github.com/XTLS/Xray-rules-dat)
- 配置模板 [Xray-examples](https://github.com/XTLS/Xray-examples)
- xray 文档 [XTLS.github.io](https://github.com/XTLS/XTLS.github.io)

您可以使用 [Git](https://git-scm.com/) 来获取代码.

### 分支(Branch)

本项目的主干分支为 main, main 分支也是发布时所使用的代码分支, 因此需要确保 master 在任一时刻都是可编译可使用的。

如果需要开发新的功能

- 请新开分支进行开发, 在开发完成并且经过充分测试后, 合并回主干分支.
- 新开分支如没有必要再存在时, 可以去除.

### 发布(Release)

<Badge text="WIP" type="warning"/>

- 建立尝鲜版本和稳定版本两个发布通道
  - 临时版本, 主要用于特定情况的测试(比如从分支 build 的), 于 TG 群内/issue 回复等渠道 发布特定版本
  - 尝鲜版本可以为 daily build , 用于尝鲜和获得即时反馈和再改进.
  - 稳定版本为定时更新(比如周更), 合并稳定的修改并发布.

### 引用其它项目

- Golang
  - 产品代码建议使用 Golang 标准库和 [golang.org/x/](https://pkg.go.dev/search?q=golang.org%2Fx) 下的库;
  - 如需引用其它项目,请事先创建 issue 讨论;
- 其它
  - 不违反双方的协议,且对项目有帮助的工具,都可以使用。

## 开发流程

### 写代码之前

发现任何问题,或对项目有任何想法,请创建 Issue 讨论以减少重复劳动和消耗在代码上的时间。

### 修改代码

- Golang
  - 请参考 [Effective Go](https://golang.org/doc/effective_go.html);
  - 每一次 push 之前,请运行:`go fmt ./...` 和 `go fmt -s -l -e -w $(find . -type f -name "*.go" ! -name "*.pb.go")`;
  - 每一次 push 之前,请确保测试通过:`go test ./...`;
  - 提交 pull request 之前,请确保新增代码有超过 70% 的代码覆盖率(code coverage);
- 其它
  - 请注意代码的可读性。

### Pull Request

- 提交 PR 之前,请先运行 `git pull https://github.com/xray/xray-core.git` 以确保 merge 可顺利进行;
- 一个 PR 只做一件事,如有对多个 bug 的修复,请对每一个 bug 提交一个 PR;
- 由于 Golang 的特殊需求(Package path),Go 项目的 PR 流程和其它项目有所不同 ,建议流程如下:
  1. 先 Fork 本项目,创建自己的 `github.com/your/Xray-core` 仓库;
  2. 克隆自己的 Xray 仓库到本地:`git clone https://github.com/your/Xray-core.git`;
  3. 基于 `main` 分支创建新的分支;
  4. 在自行创建的分支上作修改并提交修改(commit);
  5. 在推送(push)修改完成的分支到自己的仓库前,先切换到 `main` 分支,运行 `git pull https://github.com/v2fly/Xray-core.git` 拉取最新的远端代码;
  6. 如果上一步拉取得到了新的远端代码,则切换到之前自己创建的分支,运行 `git rebase master` 执行分支合并操作。如遇到文件冲突,则需要解决冲突;
  7. 上一步处理完毕后,就可以把自己创建的分支推送到自己的仓库:`git push -u origin your-branch`
  8. 最后,把自己仓库的新推送的分支往 `xtls/Xray-core` 的 `main` 分支发 PR 即可;
  9. 请在 PR 的标题和正文中,完整表述此次 PR 解决的问题 / 新增的功能 / 代码所做的修改的用意等;
  10. 耐心等待开发者的回应。

### 对代码的修改

#### 功能性问题

请提交至少一个测试用例(Test Case)来验证对现有功能的改动。

#### 性能相关

请提交必要的测试数据来证明现有代码的性能缺陷,或是新增代码的性能提升。

#### 新功能

- 如果新增功能对已有功能不影响,请提供可以开启/关闭的开关(如 flag),并使新功能保持默认关闭的状态;
- 大型新功能(比如增加一个新的协议)开发之前,请先提交一个 issue,讨论完毕之后再进行开发。

#### 其它

视具体情况而定。

## Xray 编码规范

以下内容适用于 Xray 中的 Golang 代码。

### 代码结构

```
Xray-core
├── app        // 应用模块
│   ├── router // 路由
├── common     // 公用代码
├── proxy      // 通讯协议
│   ├── blackhole
│   ├── dokodemo-door
│   ├── freedom
│   ├── socks
│   ├── vmess
├── transport  // 传输模块
```

### 编码规范

基本与 Golang 官方所推荐做法一致,有一些例外。写在这里以方便大家熟悉 Golang。

#### 命名

- 文件和目录名尽量使用单个英文单词,比如 hello.go;
  - 如果实在没办法,则目录使用连接线/文件名使用下划线连接两个(或多个单词),比如 hello-world/hello_again.go;
  - 测试代码使用 \_test.go 结尾;
- 类型使用 Pascal 命名法,比如 ConnectionHandler;
  - 对缩写不强制小写,即 HTML 不必写成 Html;
- 公开成员变量也使用 Pascal 命名法;
- 私有成员变量使用 [小驼峰式命名法](https://zh.wikipedia.org/wiki/%E9%A7%9D%E5%B3%B0%E5%BC%8F%E5%A4%A7%E5%B0%8F%E5%AF%AB) ,如 `privateAttribute` ;
- 为了方便重构,方法建议全部使用 Pascal 命名法;
  - 完全私有的类型放入 `internal` 。

#### 内容组织

- 一个文件包含一个主要类型,及其相关的私有函数等;
- 测试相关的文件,如 Mock 等工具类,放入 testing 子目录。