Wikimedia Apps/Team/Android/App hacking

We welcome volunteer contributions!
Follow the steps below to get started, and feel free to ping any member of the WMF Android dev team (bearND, dbrant, mdholloway, niedzielski) on irc://irc.freenode.net/wikimedia-mobile for assistance.

Create a developer account
See https://www.mediawiki.org/wiki/Developer_access.

Add your SSH key to Gerrit
See https://www.mediawiki.org/wiki/Gerrit/Tutorial#Set_Up_SSH_Keys_in_Gerrit.

Install JDK 7+
JDK 7 or higher is needed to build Android apps. To find your current version:

javac -version

If you need to update, downloads are available here.

Download and install Android Studio
https://developer.android.com/sdk/index.html

Run the setup wizard. Standard installation is fine. Installation will take a while.

Download the project source
git clone ssh://@gerrit.wikimedia.org:29418/apps/android/wikipedia

Note that this requires developer access.

If you prefer, you may anonymously download a copy here.

Import into Android Studio
Open Android Studio > Import project > select build.gradle from the downloaded repository.

Checkstyle-IDEA
IntelliJ's Checkstyle-IDEA plugin is useful in ensuring that your code will meet the project style guidelines.

The most recent version of this plugin has caused problems; download a working version here.

To install: Android Studio > Configure > Plugins > Install plugin from disk > select downloaded file.

Restart to complete the installation, then add the checkstyle configuration file:

Android Studio > Configure > Preferences > Other Settings > click on the '+' in the upper pane and select checkstyle.xml from the repository.

Make sure you activate the new configuration file by checking the check box next to it, so our checkstyle rules are enabled and deviations show up as errors in the code editor.

Install and configure git-review
Install git-review:

sudo pip install git-review

Then create the file ~/.config/git-review/git-review.conf containing the following lines:

[gerrit] defaultremote = origin

Make changes and submit for review via Gerrit
Make changes and squash into a single commit, then:

git review -R

See here for details.

Update bundled CSS files
The various CSS files for this project are generated by the *.less files found in the MobileFrontend and MobileApp MediaWiki extensions.

You'll need a MediaWiki installation, MediaWiki-Vagrant recommended, to generate them.

In the ./vagrant directory:

vagrant enable-role mobileapp vagrant provision

Change the url in scripts/make-css-assets.bash to http://127.0.0.1:8080/w instead of the bits url, then run the script and test.

Note: your system may be unable to run the Android emulator and a Vagrant / VirtualBox instance simultaneously.

Update bundled JavaScript
Portions of JavaScript code run inside the WebView component that displays articles.

This code is prepackaged using Grunt, which must be re-run every time the master .js files are edited before building.

Preparing:

First, install the Grunt CLI tool:

npm install -g grunt-cli

Install dependencies for packaging:

cd www npm install

Building: cd www grunt

This will produce output files under wikipedia/assets which will be included in the .apk.

Update icons from SVG
Many of our icons are maintained as SVG originals, rasterized to PNG at the various output resolutions via a script. This rasterization is not part of the main build process, so needs to be re-run when adding new icons.

Setup
Install sh python module:

pip install sh

Ensure you have librsvg and the 'rsvg-convert' command:


 * On Ubuntu:
 * On Mac OS X using Homebrew:

You also need to have ImageMagick (for flipping of icons):


 * On Ubuntu:
 * On Mac OS X using Homebrew:

Lastly, you'll need the pngcrush utility, which optimizes PNG files:


 * On Ubuntu:
 * On Mac OS X using Homebrew:

Run
python scripts/convert-icons.py

Original files from icon-svgs/*/*.svg are rendered and copied into the res/ subdirectories. Note that they are not automatically added to git!

Setup
sudo pip install unicodecsv sudo pip install jinja2

Run
cd scripts python make-templates.py mv *.java ../wikipedia/src/main/java/org/wikipedia/staticdata/

Conventions

 * Java code must run cleanly against Checkstyle
 * JavaScript must run cleanly against JSHint
 * We're working to be lint free! Currently Android Linting has many offenders but new contributions should help us progress towards zero.
 * Python changes should run cleanly against flake8.
 * All Android and JVM unit tests should pass.
 * Git commit messages should conform to the MediaWiki commit message guidelines
 * Documentation should conform to the Wikipedia manual of style
 * When making changes to any strings.xml, corresponding explanatory text should be added to values-qq/strings.xml
 * Third-party libraries must meet acceptance criteria

WebView debugging in Chrome
Wikipedia for Android makes extensive use of WebViews. To debug WebView activity, navigate Google Chrome to chrome://inspect/#devices, then click on the topmost “inspect” link under “WebView in org.wikipedia.” From there you can debug the WebView like any other web site in Chrome.

Useful Gradle commands
If you prefer command line use the wrapper script in the root of the repo: ./gradlew

To run a clean debug build: ./gradlew -q clean assembleAlphaDebug

You can skip the clean part usually, which makes it much faster (from 1m:05s to 7s on my box): ./gradlew -q assembleAlphaDebug

To install build on device/emulator: ./gradlew -q installAlphaDebug

To see ProGuard output: ./gradlew clean --info proguardBetaRelease

To run checkstyle: ./gradlew checkstyle

To run Lint: ./gradlew lintAlphaDebug

To run tests: ./gradlew wikipedia:connectedAndroidTestAlphaDebug

To refresh dependencies (usually not needed): ./gradlew --refresh-dependencies

To list dependencies: ./gradlew wikipedia:dependencies --configuration compile

Help make it better!
Testing:
 * Alpha release
 * Beta release
 * Production release

See pending/recent code reviews:
 * Wikipedia Android app
 * Java MediaWiki-API
 * MediaWiki MobileApp extension