Contribution Guidelines - Scrcpy for Android

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Code of Conduct
Code Style
Java Conventions
Code Formatting
Compiler Warnings
Commit Message Format
Structure
Types
Examples
Pull Request Process
Before Submitting
Submitting Your PR
PR Template
Review Process
Testing Requirements
Manual Testing Checklist
Test Build Variants
Documentation Updates
When to Update Docs
Documentation Files
License
What This Means
Contributing Code
Reporting Bugs
Before Reporting
Bug Report Template
Getting Logs
Feature Requests
Proposing Features
Feature Request Template
Implementing Features
Getting Help
Recognition

Code of Conduct

By participating in this project, you agree to:

Be respectful and inclusive
Focus on constructive feedback
Help create a welcoming environment for all contributors
Follow the project’s technical standards

Code Style

Java Conventions

Follow the existing code style in the project:

package org.client.scrcpy;

import android.content.Context;
import android.util.Log;

/**
 * Brief description of the class
 */
public class ExampleClass {
    private static final String TAG = "ExampleClass";
    
    private Context context;
    
    public ExampleClass(Context context) {
        this.context = context;
    }
    
    public void exampleMethod() {
        // Implementation
    }
}

Code Formatting

Indentation
Braces
Line Length

Use 4 spaces for indentation (no tabs)
Consistent with existing files in app/src/main/java/ and server/src/main/java/

// Opening brace on same line
if (condition) {
    doSomething();
} else {
    doSomethingElse();
}

// Always use braces, even for single statements
if (condition) {
    doSomething();
}

Compiler Warnings

The project is configured to show unchecked and deprecation warnings:

options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"

Fix all compiler warnings before submitting your PR. Clean builds should produce no warnings.

Commit Message Format

Write clear, descriptive commit messages following this format:

Structure

<type>: <short summary in present tense>

<optional detailed description>

<optional footer>

Types

feat: New feature or functionality
fix: Bug fix
refactor: Code restructuring without behavior change
perf: Performance improvements
docs: Documentation changes
style: Code formatting, missing semicolons, etc.
test: Adding or updating tests
build: Build system or dependency changes
chore: Maintenance tasks

Examples

feat: add support for IPv6 addresses

Implement IPv6 address parsing and connection handling.
Users can now connect using format [2000::1]:5555.

Closes #42

Pull Request Process

Before Submitting

Fork and Branch

Fork the repository and create a feature branch:

git checkout -b feat/your-feature-name
# or
git checkout -b fix/issue-description

Make Your Changes

Follow the code style guidelines
Keep commits atomic and focused
Test your changes thoroughly

Test Locally

Verify your changes work:

# Build both modules
./gradlew clean assembleDebug

# Install and test
./gradlew installScrcpyDebug

Test on both:

Physical devices
Emulators (if applicable)

Update Documentation

Update relevant documentation files
Add code comments for complex logic
Update README.md if adding user-facing features

Submitting Your PR

Push to Your Fork
```
git push origin feat/your-feature-name
```
Create Pull Request
- Go to the original repository on GitHub
- Click “New Pull Request”
- Select your fork and branch
- Fill out the PR template
PR Description Should Include
- Clear description of what changed and why
- Screenshots/videos for UI changes
- Testing steps performed
- Related issue numbers (e.g., “Fixes #123”)

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tested on physical device
- [ ] Tested on emulator
- [ ] Built debug and release variants

## Screenshots
(if applicable)

## Related Issues
Closes #(issue number)

Review Process

Code Review

Maintainers will review your code
Address feedback promptly
Push additional commits to the same branch
Don’t force-push after review has started

CI Checks

All builds must pass
No new compiler warnings
Code must compile for both debug and release

Merge Criteria

Your PR will be merged when:

All review comments are addressed
CI builds pass
At least one maintainer approves
No merge conflicts exist

Testing Requirements

Manual Testing Checklist

Before submitting, test these scenarios:

Test Build Variants

Always test both build types:

# Debug build
./gradlew assembleDebug installScrcpyDebug

# Release build (if you have signing configured)
./gradlew assembleRelease

Documentation Updates

When to Update Docs

Update documentation when you:

Add new features or functionality
Change existing behavior
Fix bugs that affect user experience
Add configuration options
Change build requirements

Documentation Files

README.md

User-facing instructions and feature descriptions

Code Comments

Inline documentation for complex logic

JavaDoc

API documentation for public methods/classes

Docs Site

Comprehensive guides and tutorials

License

Scrcpy for Android is licensed under the GNU General Public License v3.0 (GPL-3.0).

What This Means

The software is free and open source
You can modify and distribute the software
Modified versions must also be GPL-3.0 licensed
You must disclose source code when distributing
Changes must be documented

Contributing Code

By contributing to this project, you agree that:

Your contributions will be licensed under GPL-3.0
You have the right to submit the code
You grant the project maintainers the right to use your contribution

Add this to new files you create:

/*
 * Copyright (C) 2024 Scrcpy for Android Contributors
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 */

Reporting Bugs

Before Reporting

Search Existing Issues

Check if the bug has already been reported:

Search open and closed issues
Look for similar problems
Check if it’s already fixed in main branch

Gather Information

Collect the following details:

Scrcpy for Android version
Android version of both devices
Device models
Steps to reproduce
Expected vs actual behavior
Logcat output

Verify the Bug

Test on latest version
Try to reproduce consistently
Test on different devices if possible

Bug Report Template

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots/Logs**
Paste logcat output or attach screenshots.

**Environment**
- App version: [e.g., 1.1.0]
- Controlling device: [e.g., Pixel 6, Android 12]
- Target device: [e.g., Samsung S21, Android 13]
- Network: [Same WiFi / Public IP / etc.]

**Additional context**
Any other relevant information.

Getting Logs

Capture logs to help debug:

# Start logging
adb logcat -c  # Clear previous logs
adb logcat > scrcpy_bug_logs.txt

# Reproduce the issue
# Then stop logging (Ctrl+C)

# Or get last 500 lines
adb logcat -d -t 500 > scrcpy_bug_logs.txt

Feature Requests

Proposing Features

We welcome feature suggestions! Before proposing:

Check Existing Requests

Search issues for similar requests
Review closed feature requests
Check the project roadmap if available

Consider Scope

Good feature requests:

Align with project goals
Benefit multiple users
Are technically feasible
Don’t overcomplicate the app

Provide Details

Include in your request:

Clear use case and motivation
Expected behavior description
UI/UX mockups (if applicable)
Technical approach (if you have ideas)

Feature Request Template

**Is your feature request related to a problem?**
A clear description of the problem. Ex. I'm always frustrated when [...]

**Describe the solution you'd like**
What you want to happen.

**Describe alternatives you've considered**
Other solutions or features you've considered.

**Use Cases**
Who would benefit and how?

**Additional context**
Mockups, diagrams, or examples from other apps.

Implementing Features

Interested in implementing a feature yourself?

Comment on the feature request issue
Discuss approach with maintainers
Wait for approval before starting work
Follow the PR process outlined above

Getting Help

If you need assistance:

GitHub Issues

For bug reports and feature requests

GitHub Discussions

For questions and community support

Code Review

Tag maintainers in your PR for review

Documentation

Check the docs for guides and references

Be patient and respectful. Maintainers are volunteers who contribute in their free time.

Recognition

Contributors are recognized in:

GitHub contributors list
Release notes for significant contributions
Code comments for complex implementations

Thank you for contributing to Scrcpy for Android!

Development Setup

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Architecture

API Reference

Contributing

​Code of Conduct

​Code Style

​Java Conventions

​Code Formatting

​Compiler Warnings

​Commit Message Format

​Structure

​Types

​Examples

​Pull Request Process

​Before Submitting

​Submitting Your PR

​PR Template

​Review Process

​Testing Requirements

​Manual Testing Checklist

​Test Build Variants

​Documentation Updates

​When to Update Docs

​Documentation Files

README.md

Code Comments

JavaDoc

Docs Site

​License

​What This Means

​Contributing Code

​Reporting Bugs

​Before Reporting

​Bug Report Template

​Getting Logs

​Feature Requests

​Proposing Features

​Feature Request Template

​Implementing Features

​Getting Help

GitHub Issues

GitHub Discussions

Code Review

Documentation

​Recognition

Build docs developers (and LLMs) love

Code of Conduct

Code Style

Java Conventions

Code Formatting

Compiler Warnings

Commit Message Format

Structure

Types

Examples

Pull Request Process

Before Submitting

Submitting Your PR

PR Template

Review Process

Testing Requirements

Manual Testing Checklist

Test Build Variants

Documentation Updates

When to Update Docs

Documentation Files

License

What This Means

Contributing Code

Reporting Bugs

Before Reporting

Bug Report Template

Getting Logs

Feature Requests

Proposing Features

Feature Request Template

Implementing Features

Getting Help

Recognition