Add: development

docs/development/intro/compile.md

@@ -0,0 +1,81 @@
+# 编译文档
+
+## 前序工作
+
+Xray 使用 [Golang](https://golang.org/) 作为编程语言，你需要先安装最新版本 Golang 才能够编译。
+
+::: tip TIP
+安装 Golang: [golang.org/doc/install](https://golang.org/doc/install)
+:::
+
+> 如果你不幸使用 Windows, 请 **务必** 使用 Powershell
+
+## 拉取 Xray 源代码
+
+```bash
+git clone https://github.com/XTLS/Xray-core.git
+cd Xray-core && go mod download
+```
+
+> 如果你闲的没事干，可以试试 GitHub 官方工具: `gh repo clone XTLS/Xray-core`
+
+注意：在无法正常访问 Google 的网络环境，依赖无法被正常拉取，需要先设置 `GOPROXY`：
+
+```bash
+go env -w GOPROXY=https://goproxy.io,direct
+```
+
+## 构建二进制
+
+:::warning
+本小节的命令需要在 Xray 根目录内运行。
+:::
+
+### Windows(Powershell):
+
+```powershell
+$env:CGO_ENABLED=0
+go build -o xray.exe -trimpath -ldflags "-s -w -buildid=" ./main
+```
+
+### macOS, Linux:
+
+```bash
+CGO_ENABLED=0 go build -o xray -trimpath -ldflags "-s -w -buildid=" ./main
+```
+
+运行以上命令会在目录下生成 xray 可执行文件。
+
+::: tip
+如果需要编译可以进行 debug 的程序,即可以用 dlv 附加到运行的程序进行调试, 请去掉 ldflags 中的 '-w -s' 选项.
+
+-w 禁止生成 debug 信息。使用该选项后，将无法使用 gdb 进行调试。
+-s 禁用符号表
+PS:其实用 vscode 或其他 IDE 调试似乎更方便。
+:::
+
+## 交叉编译：
+
+这里以在 Windows(Powershell) 环境中，编译到 Linux 服务器为例：
+
+```powershell
+$env:CGO_ENABLED=0
+$env:GOOS="linux"
+$env:GOARCH="amd64"
+
+go build -o xray -trimpath -ldflags "-s -w -buildid=" ./main
+```
+
+上传到服务器后，记得在服务器终端内执行 `chmod +x xray`
+
+::: tip
+执行 `go tool dist list` 查看所有支持的系统与架构。
+:::
+
+## 可复现构建：
+
+按照上述步骤，能够编译与 Release 中完全相同的二进制文件。
+
+::: warning
+请先确认您使用的 Golang 版本与编译 Release 的一致。
+:::

docs/development/intro/design.md

@@ -0,0 +1,43 @@
+# 设计目标
+
+- Xray 内核提供了一个平台，支持必要的网络代理功能，在其之上可以进二次开发，以提供更好的用户体验；
+- 以跨平台为首要原则，以减少二次开发的成本；
+
+## 架构
+
+![Architecture](./framework.png)
+
+内核分为三层：应用层、代理层和传输层。
+
+每一层内包含数个模块，模块间互相独立，同类型的模块可无缝替换。
+
+### 应用层
+
+应用层包含一些代理层中常用的功能，这些功能被抽象出来，以便在不同的代理模块中复用。
+
+应用层的模块应为纯软件实现，与硬件或平台相关的技术无关。
+
+重要模块列表：
+
+- Dispatcher: 用于把入站代理所接收到的数据，传送给出站代理；
+- Router: 路由模块，详见 [路由配置](../../config/routing.md)；
+- DNS: 内置的 DNS 服务器模块；
+- Proxy Manager: 代理管理器；
+
+### 代理层
+
+代理层分为两部分：入站代理（Inbound Proxy）和出站代理（Outbound Proxy）。
+
+两部分相互独立，入站代理不依赖于某个特定的出站代理，反之亦然。
+
+#### 入站代理
+
+- 实现 [proxy.Inbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) 接口；
+
+#### 出站代理
+
+- 实现 [proxy.Outbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) 接口；
+
+### 传输层
+
+传输层提供一些网络数据传输相关的工具模块。

docs/development/intro/guide.md

@@ -0,0 +1,134 @@
+# 开发规范
+
+## 基本
+
+### 版本控制
+
+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 子目录。