Contributing Guidelines

​

How to Contribute

• Report bugs - Help us identify and fix issues
• Suggest features - Share ideas for improvements
• Write code - Fix bugs or implement new features
• Write documentation - Improve guides and API docs
• Translate - Help localize Sunshine into other languages
• Review pull requests - Provide feedback on proposed changes
• Help others - Answer questions in discussions and Discord

​

Getting Started

​

Prerequisites

1. GitHub account - Required for contributing
2. Git - For version control
3. Development environment - See Building from Source
4. Familiarity with C++ - For code contributions

​

First Steps

1. Fork the repository on GitHub
2. Clone your fork locally:
   git clone https://github.com/YOUR_USERNAME/Sunshine.git --recurse-submodules
   cd Sunshine
   
3. Create a branch for your changes:
   git checkout -b feature/my-new-feature
   
4. Make your changes (see guidelines below)
5. Test your changes thoroughly
6. Commit and push your changes
7. Open a pull request on GitHub

​

Code Style and Standards

​

C++ Code Style

find ./ -iname *.cpp -o -iname *.h -iname *.m -iname *.mm | xargs clang-format -i

​

Coding Standards

• Use C++17 or later features where appropriate
• Follow RAII principles for resource management
• Prefer std::unique_ptr and std::shared_ptr over raw pointers
• Use const wherever possible
• Write self-documenting code with clear variable names
• Add comments for complex logic

• Place platform-specific code in src/platform/<platform>/
• Use platform abstraction interfaces in src/platform/common.h
• Avoid #ifdef blocks in core code when possible

• Check return values and handle errors gracefully
• Use exceptions for exceptional conditions
• Log errors with appropriate severity levels

​

Recommended Development Tools

​

Web UI Development

​

Web UI Structure

• Location: ./src_assets/common/assets/web
• Templating: EJS (see template_header.html and template_header_main.html)
• Styling: Bootstrap 5
• Icons: Lucide and Simple Icons

​

Building the Web UI

cmake -B build -G Ninja -S . --target web-ui
ninja -C build web-ui

cd src_assets/common/assets/web
npm install
npm run dev

​

Web UI Guidelines

• Follow Vue.js best practices
• Use existing Bootstrap components when possible
• Ensure responsive design (mobile, tablet, desktop)
• Test on multiple browsers
• Keep dependencies up to date

​

Localization and Translation

​

Translation Basics

​

Adding Translatable Strings

​

Web UI (Vue.js)

{
  "index": {
    "welcome": "Hello, Sunshine!"
  }
}

<template>
  <div>
    <p>{{ $t('index.welcome') }}</p>
  </div>
</template>

• Vue I18n Formatting Guide

​

C++ Code

#include <boost/locale.hpp>
#include <string>

std::string msg = boost::locale::translate("Hello world!");

• Boost.Locale Documentation

​

Translation Workflow

1. Developer adds string to en.json (Web UI) or C++ code
2. PR is merged to master branch
3. CI workflow extracts strings and pushes to CrowdIn
4. Translators translate on CrowdIn
5. CrowdIn pushes translations to l10n_master branch
6. PR is created from l10n_master to master
7. PR is merged, translations are now available

​

Testing

​

Unit Testing

./build/tests/test_sunshine

./build/tests/test_sunshine --gtest_filter="TestSuiteName.TestName"

./build/tests/test_sunshine --gtest_verbose

./build/tests/test_sunshine --help

​

Code Coverage

• PRs must maintain or improve total coverage
• New code should have adequate test coverage

// GCOV_EXCL_START
void untestable_gpu_function() {
    // This code won't be counted in coverage
}
// GCOV_EXCL_STOP

​

Clang Format Testing

python ./scripts/update_clang_format.py

git diff

​

Pull Request Process

​

Before Submitting

• Code is formatted with clang-format
• All tests pass locally
• New features have tests
• Documentation is updated (if applicable)
• Commit messages are clear and descriptive
• Branch is up to date with master

​

Pull Request Guidelines

• Use a clear, descriptive title
• Start with a verb: “Add”, “Fix”, “Update”, “Improve”, “Remove”
• Examples:
  • “Add support for AV1 encoding”
  • “Fix crash when disconnecting client”
  • “Update documentation for KMS capture”

• Describe what changed and why
• Reference related issues: “Fixes #123” or “Related to #456”
• Include screenshots/videos for UI changes
• List breaking changes (if any)
• Explain how to test the changes

## Summary

Adds support for AV1 encoding on Linux using VAAPI.

## Changes

- Added AV1 encoder initialization in `video.cpp`
- Updated encoder selection logic
- Added AV1 configuration options

## Testing

1. Build with `SUNSHINE_ENABLE_VAAPI=ON`
2. Set encoder to "av1" in config
3. Start streaming session
4. Verify AV1 encoding in client logs

Fixes #789

​

Review Process

1. Automated checks run (CI, formatting, tests)
2. Maintainers review your code
3. Address feedback if requested
4. Approval from maintainer(s)
5. Merge to master branch

​

Reporting Bugs

• Sunshine version (e.g., v0.20.0)
• Platform (Linux, Windows, macOS, FreeBSD)
• OS version (e.g., Ubuntu 22.04, Windows 11, macOS 14)
• GPU (vendor and model)
• Steps to reproduce (detailed and numbered)
• Expected behavior
• Actual behavior
• Logs (see log locations in Architecture)
• Screenshots/videos (if applicable)

​

Feature Requests

• Check existing issues - your feature may already be requested
• Describe the use case - why is this feature needed?
• Provide examples - how would it work?
• Consider alternatives - are there other solutions?

​

Community Guidelines

​

Code of Conduct

• Be respectful - treat everyone with kindness
• Be constructive - provide helpful feedback
• Be patient - remember maintainers are volunteers
• Be inclusive - welcome all contributors

​

Communication Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: General questions and discussions
• Discord: Real-time chat and support
• Documentation: Official docs

​

Additional Resources

• LizardByte Contributing Guide
• Sunshine GitHub Repository
• CrowdIn Translation Project

​

Thank You!