Contributing

Thank you for your interest in contributing to Solstice! This guide covers everything you need to know to make high-quality contributions.

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 for your work:

   git checkout -b feature/my-feature

4. Set up the development environment - follow Getting Started

---

Project Architecture

Before contributing, read the Architecture document to understand the hybrid Go + Python design. Key points:

• Go handles all Bot API interactions, database, and queue management
• Python handles only voice chat streaming (PyTgCalls)
• They communicate via localhost HTTP (ports 5050/5051)
• All state is in MongoDB; all caching in Upstash Redis

---

Code Organization

Go Code (internal/)

Directory	Convention
telegram/	One file per feature module (admins.go, fun.go, tools.go, etc.)
database/	All DB functions in a single file (db.go) - package-level functions
config/	Single file, singleton pattern
queue/	Single file, mutex-protected struct
youtube/	One file per concern (search, extraction, cache, proxy)

Adding a New Command

1. Create the handler function in the appropriate file:

   func (h *BotHandler) handleMyCommand(c telebot.Context) error {
       // Your logic here
       return c.Reply("Response")
   }

2. Register it in the corresponding Init*() function:

   func (h *BotHandler) InitTools() {
       // ... existing handlers
       h.Bot.Handle("/mycommand", h.handleMyCommand)
   }

3. Add help text to strings/langs/en.yml
4. Update the help menu in help.go if applicable

Adding a New Language String

1. Add the key to strings/langs/en.yml:

   my_key: "Hello {0}, welcome to {1}!"

2. Use it in code:

   text := i18n.GetString("my_key", userName, chatName)

---

Code Style

Go

• Follow standard gofmt formatting
• Use descriptive function names (handleBan, not hBan)
• Keep sassy bot personality in user-facing strings
• Use h.logError() for all error logging
• Always check h.CheckAdminSassy(c) for admin commands
• Use h.getTargetUser(c) for resolving target users

Python

• Follow PEP 8
• Use async/await for all I/O operations
• Keep the daemon focused - no business logic (that belongs in Go)

Commit Messages

Use Conventional Commits:

feat: add /dice command with random roll
fix: resolve race condition in queue shuffle
docs: update command reference with new flags
refactor: extract proxy pool into separate package

---

Pull Request Process

1. Ensure your code builds: go build ./...
2. Test your changes manually with a bot instance
3. Update documentation if you added/changed commands
4. Push to your fork and open a PR against main
5. Describe what your PR does and why

PR Title Format

feat: Brief description of the feature
fix: Brief description of the bug fix
docs: Brief description of documentation change

---

Development Tips

Running in Development Mode

Set DEVELOPER_MODE=true in .env for verbose logging.

Testing Without Voice Chat

You can test all non-VC commands without the Python daemon running. The bot will still respond to admin, fun, utility, and management commands.

Useful Commands During Development

# Build and run in one step
go run cmd/bot/main.go

# Check for compilation errors without building
go vet ./...

# Format all Go files
gofmt -w .

# Update Go dependencies
go mod tidy

---

Reporting Issues

When reporting bugs, include:

1. Steps to reproduce the issue
2. Expected behavior vs actual behavior
3. Error logs (from the logger channel or console)
4. Environment (OS, Go version, Python version)

---

License

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