Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
276 lines (183 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

276 lines (183 loc) · 10.1 KB
Raw

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

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

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):

    ./runSUI.sh

    This runs ./build.sh then SUI_DB_FOLDER="db" SUI_DEBUG=true ./sui.

  2. Or build manually:

    ./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):

    cd frontend
npm install
npm run build
cd ..

  2. Replace web assets and build backend:

    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,with_tailscale" -o sui main.go

  3. Run:

    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, with_tailscale

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)

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.

  • Run gofmt (or goimports) before committing:

    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:

    go build -ldflags "-w -s" -tags "with_quic,with_grpc,with_utls,with_acme,with_gvisor,with_tailscale" -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)

go vet ./...
# Optional: staticcheck, golangci-lint, etc.

Features That Need Help

Community help is especially valuable in these areas. Check the 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).
  • 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

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.
    • Run gofmt and ensure the project builds (see 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:

    **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

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.