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 pure Go architecture. Key points:

• Go handles everything: Bot API interactions, database, queue, and voice streaming via CGo libntgcalls
• Embedded Web Server hosts the WebSocket hub and Web Room
• All voice streaming runs in-process with zero external daemons
• All state is in MongoDB; all stream 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

Commit Messages

Write natural, direct commit messages like a human developer (never use conventional prefixes like feat:, fix:, or chore:):

Add dice command with random roll
Resolve race condition in queue shuffle
Update command reference with new flags
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 dev (never target main)
5. Describe what your PR does and why

PR Title Format

Brief description of the feature or bug fix

---

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 configuring an assistant session string. 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)

---

License

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