132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
# Development Standards
|
|
|
|
## Basic
|
|
|
|
### Version Control
|
|
|
|
Project X's code is hosted on GitHub:
|
|
|
|
- Xray Core [xray-core](https://github.com/XTLS/Xray-core)
|
|
- Installation script [Xray-install](https://github.com/XTLS/Xray-install)
|
|
- Configuration template [Xray-examples](https://github.com/XTLS/Xray-examples)
|
|
- Xray documentation [Xray-docs-next](https://github.com/XTLS/Xray-docs-next)
|
|
|
|
You can use [Git](https://git-scm.com/) to get the code.
|
|
|
|
### Branch
|
|
|
|
- The main branch is the backbone of this project.
|
|
- The main branch is also the release branch of this project.
|
|
- It is necessary to ensure that main can be compiled and used normally at any time.
|
|
- If you need to develop new features, please create a new branch for development. After development and sufficient testing, merge it back to the main branch.
|
|
- Please delete branches that have been merged into the main branch and are no longer necessary.
|
|
|
|
### Release
|
|
|
|
<Badge text="WIP" type="warning"/> (Note: this is not translatable as it is a technical tag)
|
|
|
|
- Create two release channels: one for the beta version and another for the stable version.
|
|
- The beta version, also known as the daily build, is mainly used for specific testing, experimentation, and instant feedback and improvement.
|
|
- The stable version, updated regularly (e.g. monthly), merges stable modifications and releases them.
|
|
|
|
### Citing other projects
|
|
|
|
- Golang
|
|
- It is recommended to use the Golang standard library and libraries under [golang.org/x/](https://pkg.go.dev/search?q=golang.org%2Fx) for product code;
|
|
- If you need to reference other projects, please create an issue for discussion beforehand;
|
|
- Other
|
|
- Tools that do not violate the agreement of both parties and are helpful to the project can be used.
|
|
|
|
## Development Process
|
|
|
|
### Before Writing Code
|
|
|
|
If you encounter any issues or have any ideas for the project, please create an [issue](https://github.com/XTLS/Xray-core/issues) for discussion to reduce redundant work and save time spent on coding.
|
|
|
|
### Modify the code
|
|
|
|
- Golang
|
|
- Please refer to [Effective Go](https://golang.org/doc/effective_go.html);
|
|
- Run `go generate core/format.go` before each push;
|
|
- If you need to modify protobuf, such as adding new configuration items, please run: `go generate core/proto.go`;
|
|
- It is recommended to pass the test before submitting a pull request: `go test ./...`;
|
|
- It is recommended to have more than 70% code coverage for newly added code before submitting pull requests.
|
|
- Other
|
|
- Please pay attention to the readability of the code.
|
|
|
|
### Pull Request
|
|
|
|
- Before submitting a PR, please run `git pull https://github.com/xray/xray-core.git` to ensure that the merge can proceed smoothly;
|
|
- One PR only does one thing. If there are fixes for multiple bugs, please submit a PR for each bug;
|
|
- Due to Golang's special requirements (Package path), the PR process for Go projects is different from other projects. The recommended process is as follows:
|
|
1. Fork this project first and create your own `github.com/<your_name>/Xray-core.git` repository;
|
|
2. Clone your own Xray repository to your local machine: `git clone https://github.com/<your_name>/Xray-core.git`;
|
|
3. Create a new branch based on the `main` branch, for example `git branch issue24 main`;
|
|
4. Make changes on the new branch and commit the changes;
|
|
5. Before pushing the modified branch to your own repository, switch to the `main` branch, and run `git pull https://github.com/xray/xray-core.git` to pull the latest remote code;
|
|
6. If new remote code is obtained in the previous step, switch to the branch you created earlier and run `git rebase main` to perform branch merging. If there is a file conflict, you need to resolve the conflict;
|
|
7. After the previous step is completed, you can push the branch you created to your own repository: `git push -u origin your-branch`
|
|
8. Finally, send a PR from your new pushed branch in your own repository to the `main` branch of `xtls/Xray-core`;
|
|
9. Please fully describe the purpose of this PR, including the problem solved, the new feature added, or the modifications made in the title and body of the PR;
|
|
10. Please be patient and wait for the developer's response.
|
|
|
|
### Modifying Code
|
|
|
|
#### Functional issue
|
|
|
|
Please submit at least one test case to verify changes to existing functionality.
|
|
|
|
#### Performance Related
|
|
|
|
Please provide the necessary test data to demonstrate performance issues in existing code or performance improvements in new code.
|
|
|
|
#### New Feature
|
|
|
|
- If the new feature does not affect the existing functionality, please provide a toggle (such as a flag) that can be turned on/off, and keep the new feature disabled by default.
|
|
- For major new features (such as adding a new protocol), please submit an issue for discussion before development.
|
|
|
|
#### Other
|
|
|
|
It depends on the specific situation.
|
|
|
|
## Xray Coding Guidelines
|
|
|
|
The following content is applicable to Golang code in Xray.
|
|
|
|
### Code Structure
|
|
|
|
```
|
|
Xray-core
|
|
├── app // Application module
|
|
│ ├── router // Router
|
|
├── common // Common code
|
|
├── proxy // Communication protocol
|
|
│ ├── blackhole
|
|
│ ├── dokodemo-door
|
|
│ ├── freedom
|
|
│ ├── socks
|
|
│ ├── vmess
|
|
├── transport // Transport module
|
|
```
|
|
|
|
### Coding Standards
|
|
|
|
Basic practices are consistent with the recommendations of the official Golang, with a few exceptions. Written here to help everyone familiarize themselves with Golang.
|
|
|
|
#### Naming
|
|
|
|
- Use a single English word for file and directory names, such as hello.go;
|
|
- If not possible, use a hyphen for directories / underscore for files to connect two (or more) words, such as hello-world/hello_again.go;
|
|
- Use \_test.go to name test code files;
|
|
- Use PascalCase for types, such as ConnectionHandler;
|
|
- Do not force lowercase for abbreviations, i.e. HTML does not need to be written as Html;
|
|
- Use PascalCase for public member variables;
|
|
- Use camelCase for private member variables, such as `privateAttribute`;
|
|
- For easy refactoring, it is recommended to use PascalCase for all methods;
|
|
- Place completely private types in `internal`.
|
|
|
|
#### Content Organization
|
|
|
|
- A file contains a main type and its related private functions;
|
|
- Testing-related files, such as Mock tools, should be placed in the testing subdirectory.
|