From bdc25bb3d6b0bcd2c3e7bcb8eb6d1fa8191e8ad2 Mon Sep 17 00:00:00 2001 From: Alireza Ahmadi Date: Thu, 12 Feb 2026 23:43:51 +0100 Subject: [PATCH] Add contribution guide #111 --- CONTRIBUTING.md | 276 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +- 2 files changed, 279 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3453d3c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,276 @@ +# Contributing to S-UI + +Thank you for your interest in contributing to S-UI. This document explains how to set up a development environment, follow project conventions, and submit changes. Your contributions help make the **multi-inbound-per-user** approach and the rest of the project better for everyone. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Development Environment Setup](#development-environment-setup) +- [Coding Conventions and Style Guide](#coding-conventions-and-style-guide) +- [Testing](#testing) +- [Features That Need Help](#features-that-need-help) +- [Pull Request Process](#pull-request-process) +- [Adding This Guide in Your Repository](#adding-this-guide-in-your-repository) +- [Reporting Bugs and Requesting Features](#reporting-bugs-and-requesting-features) + +--- + +## Code of Conduct + +Please be respectful and constructive when interacting with maintainers and other contributors. This project is for personal learning and communication; use it responsibly and legally. + +--- + +## Development Environment Setup + +### Prerequisites + +- **Go**: 1.25 or later (see `go.mod` for the exact version). +- **Git**: For cloning and submodules. +- **C compiler**: Required for CGO (e.g. `gcc`, `musl-dev` on Alpine). +- **Node.js** (optional): Only if you plan to work on or rebuild the frontend. The repo can be run with pre-built frontend assets. + +### Clone and Submodules + +```bash +git clone https://github.com/alireza0/s-ui +cd s-ui +git submodule update --init --recursive +``` + +The **frontend** lives in a submodule. If you only work on the backend, you can use the existing `web/html` contents or build the frontend once (see below). + +### Backend-Only Development (quickest) + +1. Build and run with the provided script (builds backend and runs with debug + local DB): + + ```bash + ./runSUI.sh + ``` + + This runs `./build.sh` then `SUI_DB_FOLDER="db" SUI_DEBUG=true ./sui`. + +2. Or build manually: + + ```bash + ./build.sh + SUI_DB_FOLDER=db SUI_DEBUG=true ./sui + ``` + + Default panel: **http://localhost:2095/app/** (user: `admin`, password: `admin` — change in production). + +### Full Stack (Backend + Frontend) + +1. **Frontend** (separate repo in submodule): + + ```bash + cd frontend + npm install + npm run build + cd .. + ``` + +2. **Replace web assets and build backend**: + + ```bash + mkdir -p web/html + rm -rf web/html/* + cp -R frontend/dist/* web/html/ + go build -ldflags "-w -s" -tags "with_quic,with_grpc,with_utls,with_acme,with_gvisor" -o sui main.go + ``` + +3. Run: + + ```bash + SUI_DB_FOLDER=db SUI_DEBUG=true ./sui + ``` + +### Build Tags + +The backend is built with these tags for full functionality: + +- `with_quic`, `with_grpc`, `with_utls`, `with_acme`, `with_gvisor` + +Use the same tags when building locally if you need feature parity with releases. + +### Environment Variables (development) + +| Variable | Description | Example | +|----------------|--------------------------------|-----------| +| `SUI_DB_FOLDER`| Directory for SQLite DB files | `db` | +| `SUI_DEBUG` | Enable debug mode | `true` | +| `SUI_LOG_LEVEL`| Log level | `debug` | +| `SUI_BIN_FOLDER` | Directory for binaries | `bin` | + +### Docker (optional) + +```bash +git clone https://github.com/alireza0/s-ui +cd s-ui +git submodule update --init --recursive +docker build -t s-ui . +# or: docker compose up -d +``` + +--- + +## Coding Conventions and Style Guide + +### General + +- Write clear, maintainable code. Prefer small, focused functions and packages. +- Comment non-obvious logic and public APIs. +- Handle errors explicitly; avoid ignoring `err` unless intentional. + +### Go Style + +- Follow **standard Go style** and **[Effective Go](https://go.dev/doc/effective_go)**. +- Run **gofmt** (or **goimports**) before committing: + + ```bash + gofmt -w . + # or: goimports -w . + ``` + +- Use **camelCase** for unexported names and **PascalCase** for exported names. +- Keep package names short and lowercase (e.g. `api`, `service`, `util`). +- Group imports: standard library, then third-party, then project imports (as in existing files). + +### Project Structure Conventions + +- **`api/`**: HTTP handlers and API routing (e.g. `apiHandler.go`, `apiV2Handler.go`). +- **`service/`**: Business logic and panel/core operations. +- **`database/model/`**: GORM models and DB entities. +- **`util/`**: Shared utilities (e.g. link/sub conversion, JSON). +- **`core/`**: sing-box integration and core runtime. +- **`sub/`**: Subscription (link/json) handling. + +When adding new features, place code in the appropriate layer (handler → service → model/util) and avoid circular dependencies. + +### Naming and Patterns + +- Handlers: suffix `Handler` (e.g. `APIHandler`, `APIv2Handler`). +- Services: suffix `Service` or use package name (e.g. `ApiService`, `LinkService`). +- Models: clear struct names with JSON/gorm tags (see `database/model/`). + +--- + +## Testing + +### Current State + +- The project does not yet have a formal test suite (no `*_test.go` files in the repo). +- CI currently focuses on **builds** (e.g. `release.yml`) rather than automated tests. + +### What You Can Do Now + +1. **Build verification**: Before submitting a PR, ensure the project builds: + + ```bash + go build -ldflags "-w -s" -tags "with_quic,with_grpc,with_utls,with_acme,with_gvisor" -o sui main.go + ``` + +2. **Manual testing**: Run with `./runSUI.sh`, test the changed area (panel, API, subscription, etc.). + +3. **Future tests**: Contributions that add **unit tests** (e.g. for `util/`, `service/`, or API handlers) or **integration tests** are very welcome. Prefer the standard library `testing` package and table-driven tests where appropriate. + +### Running the Linter (optional) + +```bash +go vet ./... +# Optional: staticcheck, golangci-lint, etc. +``` + +--- + +## Features That Need Help + +Community help is especially valuable in these areas. Check the [Issues](https://github.com/alireza0/s-ui/issues) for current tasks and ideas. + +### High-Value Areas + +- **Multi-inbound per user**: Core differentiator of S-UI; improvements to UX, docs, and robustness are welcome. +- **API (v1 and v2)**: Completeness, consistency, and documentation (see [API Documentation](https://github.com/alireza0/s-ui/wiki/API-Documentation)). +- **Subscription service**: Link conversion, JSON subscription, and info endpoints (`sub/`, `util/`). +- **Testing**: Adding unit and integration tests for critical paths. +- **Documentation**: User docs, API examples, and contribution docs (like this file). +- **Platform support**: macOS is experimental; Windows and Linux improvements are welcome (see `windows/` and `.github/workflows/`). + +### How to Find Tasks + +- **Good first issue**: Look for issues labeled `good first issue` or `help wanted`. +- **Feature requests**: [Feature request template](.github/ISSUE_TEMPLATE/feature_request.md). +- **Bugs**: [Bug report template](.github/ISSUE_TEMPLATE/bug_report.md). + +If you want to work on a larger feature, open an issue first to discuss approach and avoid duplicate work. + +--- + +## Pull Request Process + +1. **Fork and branch** + + - Fork the repository on GitHub. + - Create a branch from `main`: e.g. `git checkout -b fix/issue-123` or `feature/sub-improvements`. + +2. **Make your changes** + + - Follow the [Coding Conventions](#coding-conventions-and-style-guide). + - Run `gofmt` and ensure the project builds (see [Testing](#testing)). + - Keep commits focused and messages clear (e.g. "Fix link conversion for VMess", "Add tests for outJson"). + +3. **Push and open a PR** + + - Push your branch and open a Pull Request against `main`. + - Use the PR description to explain: + - What problem or feature the PR addresses. + - What you changed and how to verify it. + - Reference any related issue (e.g. "Fixes #123"). + +4. **Review and CI** + + - Maintainers will review your code. CI (e.g. build workflows) must pass. + - Address feedback by pushing new commits to the same branch. + +5. **Merge** + + - Once approved and CI is green, a maintainer will merge your PR. Thank you for contributing! + +### PR Guidelines + +- Prefer **small, reviewable PRs**. Split large features into logical steps. +- Avoid unrelated changes (e.g. formatting-only or refactors in a feature PR). +- Ensure your branch is up to date with `main` before submitting (rebase or merge as the project prefers). + +--- + +## Adding This Guide in Your Repository + +If you maintain a fork or your own repository and want the contribution guide to be visible and linked properly: + +1. **Keep `CONTRIBUTING.md` in the repository root** + GitHub automatically discovers a file named `CONTRIBUTING.md` (or `CONTRIBUTING`) in the root. When someone opens a new issue or pull request, GitHub can show a link to it. The community profile also uses it for the “Contributing” section. + +2. **Link from README** + Add a short line in your main `README.md` so new contributors see it when they land on the repo, for example: + ```markdown + **Want to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding conventions, and the pull request process. + ``` + +3. **Optional: GitHub “Contributing” link** + In the repository **Settings → General → Features**, ensure “Issues” (and optionally “Discussions”) are enabled. The link to `CONTRIBUTING.md` appears when users create a new issue or PR; no extra config is needed as long as the file is in the root. + +4. **When forking** + If you fork S-UI, `CONTRIBUTING.md` is already in the repo. Update the clone URLs and repo names in this file if you want your fork’s contribution instructions to point to your own repository. + +--- + +## Reporting Bugs and Requesting Features + +- **Bugs**: Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md). Include version, OS, steps to reproduce, and expected vs actual behavior. +- **Features**: Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md). Describe the use case and, if possible, a proposed approach. +- **Questions**: Use the [question template](.github/ISSUE_TEMPLATE/question-template.md) or discussions if enabled. + +--- + +Thank you for helping S-UI grow. Your contributions make it possible for more users to adopt S-UI in production and benefit from its multi-inbound-per-user design. diff --git a/README.md b/README.md index 9182e1d..51d09e0 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ **If you think this project is helpful to you, you may wish to give a**:star2: +**Want to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding conventions, testing, and the pull request process. + [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/alireza7) @@ -25,7 +27,7 @@ | Multi-Client/Inbound | :heavy_check_mark: | | Advanced Traffic Routing Interface | :heavy_check_mark: | | Client & Traffic & System Status | :heavy_check_mark: | -| Subscription Service (link/json + info)| :heavy_check_mark: | +| Subscription Link (link/json/clash + info)| :heavy_check_mark: | | Dark/Light Theme | :heavy_check_mark: | | API Interface | :heavy_check_mark: |