mirror of
https://github.com/XTLS/Xray-docs-next.git
synced 2025-01-20 17:51:40 +03:00
154 lines
12 KiB
Markdown
154 lines
12 KiB
Markdown
# Правила разработки
|
||
|
||
## Основные принципы
|
||
|
||
### Система контроля версий
|
||
|
||
Код проекта X размещен на GitHub:
|
||
|
||
- Ядро Xray [Xray-core](https://github.com/XTLS/Xray-core)
|
||
- Скрипты установки [Xray-install](https://github.com/XTLS/Xray-install)
|
||
- Шаблоны конфигурации [Xray-examples](https://github.com/XTLS/Xray-examples)
|
||
- Документация по Xray [Xray-docs-next](https://github.com/XTLS/Xray-docs-next)
|
||
|
||
Вы можете использовать [Git](https://git-scm.com/) для получения кода.
|
||
|
||
### Ветки (Branch)
|
||
|
||
- Основной веткой проекта является main.
|
||
- Основной веткой для выпуска релизов также является main.
|
||
- Необходимо убедиться, что main в любой момент времени может быть скомпилирован и работает корректно.
|
||
- Если вам нужно разработать новую функцию, создайте новую ветку для разработки. После завершения разработки и тщательного тестирования объедините ее с основной веткой.
|
||
- Удалите ветки, которые были объединены с основной веткой и больше не нужны.
|
||
|
||
### Релизы (Release)
|
||
|
||
<Badge text="В РАЗРАБОТКЕ" type="warning"/>
|
||
|
||
- Создайте два канала выпуска: для предварительных версий и для стабильных версий.
|
||
- Предварительные версии могут быть ежедневными сборками, в основном используются для тестирования в определенных ситуациях, ознакомления с новыми функциями и получения обратной связи для дальнейшего улучшения.
|
||
- Стабильные версии выпускаются по расписанию (например, ежемесячно) и содержат стабильные изменения.
|
||
|
||
### Использование других проектов
|
||
|
||
- Golang
|
||
- В коде рекомендуется использовать стандартную библиотеку Golang и библиотеки из [golang.org/x/](https://pkg.go.dev/search?limit=25&m=package&q=golang.org%2Fx).
|
||
- Если вам нужно использовать другие проекты, сначала создайте issue для обсуждения.
|
||
- Другие
|
||
- Можно использовать любые инструменты, которые не нарушают лицензии обеих сторон и полезны для проекта.
|
||
|
||
## Процесс разработки
|
||
|
||
### Перед написанием кода
|
||
|
||
Если вы обнаружили какую-либо проблему или у вас есть идеи по улучшению проекта, создайте [issue](https://github.com/XTLS/Xray-core/issues) для обсуждения, чтобы избежать дублирования усилий и траты времени на написание кода.
|
||
|
||
### Изменение кода
|
||
|
||
- Golang
|
||
- См. [Effective Go](https://golang.org/doc/effective_go.html).
|
||
- Перед каждой отправкой (push) выполните команду: `go generate core/format.go`.
|
||
- Если вам нужно изменить protobuf, например, добавить новый параметр конфигурации, выполните команду: `go generate core/proto.go`.
|
||
- Перед отправкой pull request рекомендуется запустить тесты: `go test ./...`.
|
||
- Перед отправкой pull request рекомендуется, чтобы новый код имел покрытие кода (code coverage) не менее 70%.
|
||
- Другие
|
||
- Обратите внимание на читаемость кода.
|
||
|
||
### Запрос на включение изменений (Pull Request)
|
||
|
||
- Перед отправкой PR сначала выполните команду `git pull https://github.com/XTLS/Xray-core.git`, чтобы убедиться, что слияние пройдет гладко.
|
||
- Один PR должен решать только одну задачу. Если вы исправляете несколько ошибок, отправьте по одному PR для каждой ошибки.
|
||
- Из-за особенностей Golang (пути к пакетам) процесс PR для проектов Go отличается от других проектов. Рекомендуемый процесс следующий:
|
||
1. Сначала сделайте форк (fork) проекта, создайте свой собственный репозиторий `github.com/<your_name>/Xray-core.git`.
|
||
2. Клонируйте свой репозиторий Xray локально: `git clone https://github.com/<your_name>/Xray-core.git`.
|
||
3. Создайте новую ветку на основе ветки `main`, например, `git branch issue24 main`.
|
||
4. Внесите изменения в новую ветку и зафиксируйте их (commit).
|
||
5. Перед отправкой (push) измененной ветки в свой репозиторий переключитесь на ветку `main` и выполните команду `git pull https://github.com/XTLS/Xray-core.git`, чтобы получить последнюю версию кода.
|
||
6. Если на предыдущем шаге были получены новые изменения, переключитесь на созданную вами ветку и выполните команду `git rebase main` для слияния веток. Если возникнут конфликты файлов, их необходимо разрешить.
|
||
7. После завершения предыдущего шага вы можете отправить свою ветку в свой репозиторий: `git push -u origin your-branch`.
|
||
8. Наконец, отправьте PR из своей ветки в ветку `main` репозитория `XTLS/Xray-core`.
|
||
9. В заголовке и описании PR четко опишите проблему, которую решает этот PR / новую функцию / цель изменений кода.
|
||
10. Дождитесь ответа разработчиков.
|
||
|
||
### Изменения кода
|
||
|
||
#### Проблемы с функциональностью
|
||
|
||
Отправьте хотя бы один тестовый пример (Test Case), чтобы проверить изменения в существующей функциональности.
|
||
|
||
#### Проблемы с производительностью
|
||
|
||
Отправьте необходимые тестовые данные, чтобы подтвердить проблемы с производительностью существующего кода или улучшение производительности нового кода.
|
||
|
||
#### Новые функции
|
||
|
||
- Если новая функция не влияет на существующую функциональность, предоставьте переключатель (например, флаг) для ее включения/отключения и оставьте ее отключенной по умолчанию.
|
||
- Перед разработкой новой крупной функции (например, добавления нового протокола) создайте issue для обсуждения.
|
||
|
||
#### Другое
|
||
|
||
Зависит от конкретной ситуации.
|
||
|
||
## Стандарты кодирования Xray
|
||
|
||
Следующие правила применяются к коду Golang в Xray.
|
||
|
||
### Структура кода
|
||
|
||
```
|
||
Xray-core
|
||
├── app // Модули приложений
|
||
│ ├── router // Маршрутизация
|
||
├── common // Общий код
|
||
├── proxy // Протоколы связи
|
||
│ ├── blackhole
|
||
│ ├── dokodemo-door
|
||
│ ├── freedom
|
||
│ ├── socks
|
||
│ ├── vmess
|
||
├── transport // Транспортные модули
|
||
```
|
||
|
||
### Стандарты кодирования
|
||
|
||
В основном соответствуют рекомендациям Golang, за некоторыми исключениями. Приведены здесь для удобства ознакомления с Golang.
|
||
|
||
#### Именование
|
||
|
||
- Для имен файлов и каталогов по возможности используйте одно английское слово, например, hello.go.
|
||
- Если это невозможно, используйте дефисы для разделения слов в имени каталога и подчеркивания для разделения слов в имени файла, например, hello-world/hello_again.go.
|
||
- Тестовый код должен иметь суффикс _test.go.
|
||
- Для типов используйте нотацию PascalCase, например, ConnectionHandler.
|
||
- Сокращения не обязательно писать в нижнем регистре, то есть HTML не нужно писать как Html.
|
||
- Для публичных переменных-членов также используйте нотацию PascalCase.
|
||
- Для приватных переменных-членов используйте [нотацию camelCase](https://ru.wikipedia.org/wiki/CamelCase), например, `privateAttribute`.
|
||
- Для удобства рефакторинга рекомендуется использовать нотацию PascalCase для всех методов.
|
||
- Полностью приватные типы помещайте в каталог `internal`.
|
||
|
||
#### Организация кода
|
||
|
||
- Один файл должен содержать один основной тип и связанные с ним приватные функции.
|
||
- Тестовые файлы, такие как Mock и другие утилиты, помещайте в подкаталог testing.
|
||
|
||
#### Int32Range
|
||
|
||
**Для конечного пользователя**
|
||
|
||
Значение, представляющее собой необязательный диапазон. Возможные варианты записи:
|
||
|
||
- Отдельное число или диапазон, заключенные в кавычки:
|
||
- `""` (считается как 0). Обратите внимание, что полное отсутствие настройки поля и установка пустого значения могут иметь разное значение.
|
||
- `"114"`
|
||
- `"114-514"`
|
||
- Отдельное целое число (int). В этом случае возможно указать только одно число:
|
||
- `114`
|
||
|
||
**Для разработчика**
|
||
|
||
Если вам нужно использовать диапазон в файле конфигурации, используйте тип `Int32Range`. Для получения значений используйте `.From` и `.To` вместо использования строкового типа (`string`) и последующего ручного разбора.
|
||
|
||
Метод `.EnsureOrder()` можно использовать для обмена значений From и To, если From больше, чем To (при необходимости).
|
||
|
||
|
||
|