Contributing Guidelines

Thank you for your interest in contributing to RUSEON Core! We welcome bug fixes, performance improvements, documentation updates, and new features from the community.

Development & Git Workflow

We follow a structured branch and PR model:

1. Fork the Repository: Create your fork on GitHub and clone it locally.
2. Create a Topic Branch: Branch off from dev using the format feat/feature-name or fix/issue-description.
3. Discuss First: For architectural changes or new APIs, open an Issue to align on design before writing large PRs.
4. Implement with Tests: All Go code must include unit tests with -race validation.
5. Format & Lint: Run golangci-lint run and cd web && npm run lint.
6. Submit a Pull Request: Target the dev branch for all PRs.

---

Conventional Commits Standard

We enforce the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Allowed Commit Types:

Type	When to Use	Example
feat	Adding a new capability or API	feat(webrtc): add whep audio track negotiation
fix	Correcting a bug or runtime defect	fix(recorder): prevent file descriptor leak on disk full
perf	Optimizing CPU, memory, or I/O	perf(buffer): eliminate cloneBytes allocation in hot path
docs	Documentation and comments only	docs(api): document query parameters for /api/v1/archive
test	Adding or updating test suites	test(e2e): add Testcontainers test for H.265 stream
refactor	Code restructuring without behavior change	refactor(db): isolate badger transaction helpers
chore	Dependency bumps, CI updates, configs	chore(deps): upgrade pion/webrtc to v4

---

Coding Standards & Best Practices

Go Code Guidelines:

• Zero Allocations on the Hot Path: Avoid allocating slices or structs in WriteFrame and media broadcasting loops.
• Context Propagation: Pass context.Context as the first argument in long-running functions and API handlers.
• Defensive Error Handling: Always check and wrap errors (fmt.Errorf("action: %w", err)). Never discard errors silently.
• Concurrency Safety: Protect shared state using sync.RWMutex or atomic primitives (sync/atomic). Always test with go test -race.

Frontend Guidelines:

• Write idiomatic TypeScript with strict type checking (noImplicitAny).
• Keep components modular and reusable under web/src/components/.
• Validate user inputs with clear visual feedback.

Related Documentation

• Development Overview
• Environment Setup
• Testing Guide
• CI/CD Workflows