Contributing

NOTE

Repository Status: SolsticeIO is currently in active private development. The repository and community contributions will open to the public soon! You can follow updates and announcements in the Telegram.

Thank you for your interest in contributing to SolsticeIO! This guide outlines how to set up your development environment, structure your code, and submit pull requests.

Getting Started

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/SolsticeIO.git
   cd SolsticeIO

3. Create a branch originating from dev:

   git checkout -b my-feature

   Note: All development must target the dev branch. Never open PRs targeting main.
4. Follow the Getting Started guide to configure your local .env.

---

Architecture Principles

Before making changes, keep these core principles in mind:

• Single Binary / Pure Go + CGo: SolsticeIO compiles down to a single binary. Voice chat WebRTC streaming runs in-process via CGo libntgcalls directly in the Go runtime.
• Embedded Web Room: Web assets (internal/web/static/) are embedded into the binary using Go's //go:embed.
• Strict Globalization (i18n): Never hardcode user-facing strings or button text in Go code. Place all strings in strings/langs/en.yml and retrieve them via i18n.GetString().
• In-Memory Caching: High-frequency lookups use the generic in-memory sliding cache (internal/cache/ttl.go) rather than polling MongoDB.

---

Code Organization

Directory	Structure & Convention
internal/telegram/	Split by domain (bot.go, admins.go, music.go, playlist.go, fun.go, tools.go, staff.go, block.go, etc.)
internal/database/	Modular database files (db.go, playlist.go, warns.go, whisper.go, welcome.go, cookies.go) with package-level functions
internal/dispatcher/	Centralized playback actions, per-chat mutex locks, and permission validation
internal/vc/	Native CGo engine (engine.go), GoGram client (assistant.go), and universal session parser (session.go)
internal/web/	Web server, WebSocket sync hub, and embedded static assets
internal/youtube/	InnerTube API, native HTML scraping, proxy pool, and yt-dlp stream extraction

Adding a New Command

1. Write the handler function in the appropriate file in internal/telegram/.
2. Register the handler in the corresponding Init*() method.
3. Add English translation keys to strings/langs/en.yml.
4. If it's a user-facing command, update all three places:
   • Root README.md
   • Documentation website (docs/commands.md)
   • Interactive help menu in internal/telegram/help.go (and help_rich_* strings in strings/langs/en.yml)

---

Commit Guidelines

Write detailed, direct commit messages. No AI Slope

---

Pull Request Process

1. Verify Builds: Ensure the Go binary compiles cleanly with CGo enabled:

   CGO_ENABLED=1 go build -trimpath ./cmd/bot/main.go

2. Verify Tests: Run tests across the packages:

   go test ./...

3. Verify Docs Build: Ensure the VitePress documentation builds without errors:

   pnpm --prefix docs build

4. Target the dev branch: Open your pull request against dev. Include a concise explanation of the changes made and why they are necessary.

---

License

By contributing to SolsticeIO, you agree that your contributions will be licensed under the GNU General Public License v3.0.