👍🎉 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 projet, 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.
I don't want to read this whole thing, I just have a question!!!
What should I know before I get started?
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 wiki to answer your question:
AdAdawy source code is an Android project organized in modules. There are four main modules:
app: The Android application itselftcpdump: A module dedicated to buildpcaplibrary andtcpdumpbinarywebserver: A module dedicated to build a simple HTTP server binary based onmongooselibraries/RootCommands: A vendorize Android library to run root shell commands
The three last modules are independant and used by the app module.
Modalirazing the application allow faster build time and simplier maintainance.
Building the project will require the latest versions of Android SDK (Software Development Kit) and NDK (Native Development kit). They can easily be installed or updated using Android Studio.
- Ensure you have Android SDK and NDK installed.
If not:
- Option 1: Install Android Studio or,
- Option 2: Install command line tools and install build tools and ndk bundle with sdk manager:
tools/bin/sdkmanager "build-tools;x.y.z" ndk-bundlewherex.y.zis the latest version
- Export
ANDROID_HOMEenvironment variable pointing to your Android SDK:
export ANDROID_HOME=/path/to/your/sdk - Launch a build:
./gradlew assembleRelease
The first full build of the apk could take a lot of time, about 20 minutes, whereas an incremental build of the app module takes less than a dozen of seconds.
In order to test the application on emulator, disable the root check in the Constants source file.
Note: Before submitting a bug report, please use the GitHub search on Issues page to check if there is already similar reports.
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as 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 logcatif 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 that gist. - Specify which version of AdAway you're using. You can get the exact version by opening in-app help and checking the last 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.
Enhancement suggestions are welcome. After refining your idea or discussing it on 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 as many details as 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.
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.
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
beginnerissues.
Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
- 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
- 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
- No maximum line width
- Split multiple attributes each on a new line
- Indent using spaces with Indention size 4
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
Please review the following commits for the changes made to the sources above in order for them to compile in this project: