> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zwc456baby/ScrcpyForAndroid/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```java Class Structure theme={null}
  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
      }
  }
  ```

  ```java Naming Conventions theme={null}
  // Classes: PascalCase
  public class DisplayWindow { }

  // Variables: camelCase
  private int maxBitrate;
  private String deviceAddress;

  // Constants: UPPER_SNAKE_CASE
  private static final int DEFAULT_PORT = 5555;
  private static final String TAG = "ScrcpyClient";

  // Methods: camelCase with verb prefix
  public void startConnection() { }
  public boolean isConnected() { }
  public int getDisplayWidth() { }
  ```
</CodeGroup>

### Code Formatting

<Tabs>
  <Tab title="Indentation">
    * Use **4 spaces** for indentation (no tabs)
    * Consistent with existing files in `app/src/main/java/` and `server/src/main/java/`
  </Tab>

  <Tab title="Braces">
    ```java theme={null}
    // Opening brace on same line
    if (condition) {
        doSomething();
    } else {
        doSomethingElse();
    }

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

  <Tab title="Line Length">
    * Prefer lines under **120 characters**
    * Break long method calls and chains appropriately
    * Use line breaks to improve readability
  </Tab>
</Tabs>

### Compiler Warnings

The project is configured to show unchecked and deprecation warnings:

```gradle theme={null}
options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"
```

<Warning>
  Fix all compiler warnings before submitting your PR. Clean builds should produce no warnings.
</Warning>

## 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

<CodeGroup>
  ```text Feature theme={null}
  feat: add support for IPv6 addresses

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

  Closes #42
  ```

  ```text Bug Fix theme={null}
  fix: prevent crash when server disconnects unexpectedly

  Add null checks in DisplayWindow to handle server disconnection
  gracefully without crashing the app.

  Fixes #78
  ```

  ```text Refactor theme={null}
  refactor: extract connection logic to separate class

  Move ADB connection handling from MainActivity to new
  ConnectionManager class for better separation of concerns.
  ```
</CodeGroup>

## Pull Request Process

### Before Submitting

<Steps>
  <Step title="Fork and Branch">
    Fork the repository and create a feature branch:

    ```bash theme={null}
    git checkout -b feat/your-feature-name
    # or
    git checkout -b fix/issue-description
    ```
  </Step>

  <Step title="Make Your Changes">
    * Follow the code style guidelines
    * Keep commits atomic and focused
    * Test your changes thoroughly
  </Step>

  <Step title="Test Locally">
    Verify your changes work:

    ```bash theme={null}
    # Build both modules
    ./gradlew clean assembleDebug

    # Install and test
    ./gradlew installScrcpyDebug
    ```

    Test on both:

    * Physical devices
    * Emulators (if applicable)
  </Step>

  <Step title="Update Documentation">
    * Update relevant documentation files
    * Add code comments for complex logic
    * Update README.md if adding user-facing features
  </Step>
</Steps>

### Submitting Your PR

1. **Push to Your Fork**
   ```bash theme={null}
   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

```markdown theme={null}
## 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

<AccordionGroup>
  <Accordion title="Code Review" icon="magnifying-glass">
    * Maintainers will review your code
    * Address feedback promptly
    * Push additional commits to the same branch
    * Don't force-push after review has started
  </Accordion>

  <Accordion title="CI Checks" icon="circle-check">
    * All builds must pass
    * No new compiler warnings
    * Code must compile for both debug and release
  </Accordion>

  <Accordion title="Merge Criteria" icon="code-merge">
    Your PR will be merged when:

    * All review comments are addressed
    * CI builds pass
    * At least one maintainer approves
    * No merge conflicts exist
  </Accordion>
</AccordionGroup>

## Testing Requirements

### Manual Testing Checklist

Before submitting, test these scenarios:

<Tabs>
  <Tab title="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
  </Tab>

  <Tab title="Display">
    * [ ] Different resolutions (720p, 1080p)
    * [ ] Different bitrates (1-8 Mbps)
    * [ ] Screen rotation
    * [ ] Aspect ratio handling
  </Tab>

  <Tab title="Input">
    * [ ] Touch events
    * [ ] Multi-touch gestures
    * [ ] Double-tap to wake
    * [ ] Navbar toggle
    * [ ] Text input
  </Tab>

  <Tab title="Edge Cases">
    * [ ] Target device locks
    * [ ] Network interruption
    * [ ] Low battery scenarios
    * [ ] Background/foreground transitions
  </Tab>
</Tabs>

### Test Build Variants

Always test both build types:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="README.md" icon="file-lines">
    User-facing instructions and feature descriptions
  </Card>

  <Card title="Code Comments" icon="comment-code">
    Inline documentation for complex logic
  </Card>

  <Card title="JavaDoc" icon="java">
    API documentation for public methods/classes
  </Card>

  <Card title="Docs Site" icon="book">
    Comprehensive guides and tutorials
  </Card>
</CardGroup>

## License

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

### What This Means

<Info>
  * 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
</Info>

### 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:

```java theme={null}
/*
 * 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

<Steps>
  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="Verify the Bug">
    * Test on latest version
    * Try to reproduce consistently
    * Test on different devices if possible
  </Step>
</Steps>

### Bug Report Template

```markdown theme={null}
**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:

```bash theme={null}
# 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:

<AccordionGroup>
  <Accordion title="Check Existing Requests" icon="list-check">
    * Search issues for similar requests
    * Review closed feature requests
    * Check the project roadmap if available
  </Accordion>

  <Accordion title="Consider Scope" icon="bullseye">
    Good feature requests:

    * Align with project goals
    * Benefit multiple users
    * Are technically feasible
    * Don't overcomplicate the app
  </Accordion>

  <Accordion title="Provide Details" icon="clipboard-list">
    Include in your request:

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

### Feature Request Template

```markdown theme={null}
**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:

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github">
    For bug reports and feature requests
  </Card>

  <Card title="GitHub Discussions" icon="comments">
    For questions and community support
  </Card>

  <Card title="Code Review" icon="code-pull-request">
    Tag maintainers in your PR for review
  </Card>

  <Card title="Documentation" icon="book-open">
    Check the docs for guides and references
  </Card>
</CardGroup>

<Note>
  Be patient and respectful. Maintainers are volunteers who contribute in their free time.
</Note>

## 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!