CONTRIBUTING.md

Contributing to AdAway

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to AdAway. These are mostly guidelines, not rules. It will help you to understand the project, find answers, deal with the source code and interact with maitainers. The project is open to any kind of contribution so feel free to share your ideas and participate to the development.

Table of contents

I don't want to read this whole thing, I just have a question!!!

What should I know before I get started?

• Discovering the project structure
• Building the project

How can I contribute?

• Reporting bugs
• Suggesting enhancements
• Translating to your language
• Your first code contribution

Styleguides

• Git commit messages
• Java styleguide
• XML styleguide

Additional notes

• tcpdump and webserver modules

I don't want to read this whole thing I just have a question!!!

Note: Please don't file an issue to ask a question. You'll get faster results by using the resources below.

We have a dedicated forum with a welcoming community and a wiki to answer your questions:

• Check the common issues and solutions on the wiki
• Read and post on the dedicated developer forum

What should I know before I get started?

Discovering the project structure

The AdAway source code is an Android project organized in modules. There are four main modules:

• app: The Android application itself
• tcpdump: A module dedicated to build the pcap library and the tcpdump binary
• webserver: A module dedicated to build a simple HTTP server binary based on mongoose
• libraries/RootCommands: A vendorize Android library to run root shell commands

The three last modules are independent and used by the app module. Modularizing the application allows for faster build times and simplier maintainance.

Building the project

Building the project will require the latest versions of the Android SDK (Software Development Kit) and NDK (Native Development kit). They can easily be installed or updated using Android Studio.

Building with Gradle

1. Ensure you have Android SDK and NDK installed. If not:
   • Option 1: Install Android Studio or,
   • Option 2: Install command line tools, build tools and ndk bundle with sdk manager:
     tools/bin/sdkmanager "build-tools;x.y.z" ndk-bundle where x.y.z is the latest version
2. Export ANDROID_HOME environment variable pointing to your Android SDK:
   export ANDROID_HOME=/path/to/your/sdk
3. Launch a build:
   ./gradlew assembleRelease

The first full build of the apk can take a lot of time, about 20 minutes, whereas an incremental build of the app module takes less than a dozen seconds.

Running on an emulator

In order to test the application on an emulator, disable the root check in the Constants source file.

How can I contribute?

Reporting bugs

Note: Before submitting a bug report, please use the GitHub search on Issues page to check if there is already similar reports.

How do I submit a (good) bug report?

• Use a clear and descriptive title for the issue to identify the problem.
• Describe the exact steps which reproduce the problem in the most detailed way possible.
• Provide specific examples to demonstrate the steps. Include hosts sources or domains you use, web pages URL you test.
• Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
• Explain which behavior you expected to see instead and why.
• If you're reporting that AdAway crashed, include a logcat. Use adb logcat if you have developer settings enabled on your device or use any application like CatLog to save logs. Include the crash report in the issue in a code block, a file attachment, or put it in a gist and provide link to it.
• Specify which version of AdAway you're using. You can get the exact version by opening in-app help and checking the About tab.
• Specify the Android version and the ROM you're using. You can also include any root or customization related information like Magisk or SuperSU version and Xposed modules is installed.

Suggesting enhancements

How do I submit a (good) enhancement suggestion?

Enhancement suggestions are welcome. After refining your idea or discussing it on the development forum, create an issue and provide the following information:

• Use a clear and descriptive title for the issue to identify the suggestion.
• Provide a step-by-step description of the suggested enhancement in the most detailed way possible, including specific examples.
• Describe the current behavior and explain which behavior you expected to see instead and why.
• Explain why this enhancement would be useful to most users.

Translating to your language

Translations are also welcome. Moreover, they do not require a development environment, only a web browser. So if you want to complete or edit your language support for the application, check the translation guide.

Your first code contribution

Unsure where to begin contributing? You can start by looking through these good first issue and help wanted issues:

• Good first issues - issues which should only require a few lines of code, and a test or two.
• Help wanted issues - issues which should be a bit more involved than beginner issues.

Both issue lists are sorted by total number of comments. While not perfect, the number of comments is a reasonable way of determining the impact a given change will have.

Style guidelines

Git commit messages

• Use the present tense ("Add feature" not "Added feature")
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit the first line to 80 characters or less
• Reference issues and pull requests liberally after the first line

Java style guidelines

• Indentation: 4 spaces, no tabs
• Maximum line width for code and comments: 100
• Opening braces don't go on their own line
• Field names: Non-public, non-static fields start with m.
• Acronyms are words: Treat acronyms as words in names, yielding !XmlHttpRequest, getUrl(), etc.

See https://source.android.com/source/code-style.html

XML style guidelines

• No maximum line width
• Split multiple attributes each on a new line
• Indent using spaces with Indention size 4

Additional notes

tcpdump and webserver modules

Origin

Forked from the following sources and slightly modified to compile:

• dnsmasq: https://github.com/CyanogenMod/android_external_dnsmasq
• libpcap: https://github.com/the-tcpdump-group/libpcap/tree/libpcap-1.7.4
• tcpdump: https://github.com/the-tcpdump-group/tcpdump/tree/tcpdump-4.7.4

Changes

Please review the following commits for the changes made to the sources above in order for them to compile in this project:

• Commit: https://github.com/AdAway/AdAway/commit/1f4ccb3cec3758757341ad90813506fc2a8fdf7b
• Commit: https://github.com/AdAway/AdAway/commit/289df896c0ac4f96bd862e8a5054f1011ec07cac
• Commit: https://github.com/AdAway/AdAway/commit/08da0745b0732b94221c0f5746160fef8126fd99