Contribution Guidelines

Guidelines for contributing code, documentation, and bug reports to Scrcpy for Android

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:

Class Structure

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

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

Braces

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

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

Line Length

• Prefer lines under 120 characters
• Break long method calls and chains appropriately
• Use line breaks to improve readability

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

Feature

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

1. 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
   
2. Make Your Changes

   • Follow the code style guidelines
   • Keep commits atomic and focused
   • Test your changes thoroughly
3. 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)
4. Update Documentation

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

Submitting Your PR

1. Push to Your Fork

   git push origin feat/your-feature-name
   

2. Create Pull Request

   • Go to the original repository on GitHub
   • Click “New Pull Request”
   • Select your fork and branch
   • Fill out the PR template

3. 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:

Connection

• Connect to device on same network
• Connect to device on public network
• IPv4 address format
• IPv6 address format
• Hostname format
• Handle connection failures gracefully

Display

• Different resolutions (720p, 1080p)
• Different bitrates (1-8 Mbps)
• Screen rotation
• Aspect ratio handling

Input

• Touch events
• Multi-touch gestures
• Double-tap to wake
• Navbar toggle
• Text input

Edge Cases

• Target device locks
• Network interruption
• Low battery scenarios
• Background/foreground transitions

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

1. 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
2. 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
3. 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?

1. Comment on the feature request issue
2. Discuss approach with maintainers
3. Wait for approval before starting work
4. 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!