s-ui/CONTRIBUTING.md

# 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.