Jump to content

Wikimedia Apps/アプリの開発

From mediawiki.org
This page is a translated version of the page Wikimedia Apps/Developing for the apps and the translation is 100% complete.
Languages:

Guidance

Making good pull requests

Ideally, pull requests from volunteers should be:

  • Small and concise, yet substantial: Your pull request should fix a single specific issue, or implement a single specific feature. Be very clear about what your pull request does, and make sure the code is clean and readable.
  • Testable: Whenever possible, include a unit test or two in your pull request.

The following kinds of pull requests are discouraged:

  • Low-effort submissions that could be done by a bot.
    • Bumping versions of library dependencies. We do try to use the latest versions of all our dependencies, but we prefer to update the version of each dependency in combination with a full regression test.
    • Updating the copyright year in our README file. It'll be OK - copyright doesn't actually expire if we forget to update the year right away.
    • Changing indentation formatting in a file, passing files through a pretty-formatter, etc. This creates unnecessary noise and churn.
  • Changing code because of personal style preferences.
    • If our code is working correctly, it really doesn't matter if it isn't in the style that you might prefer. Unless reformatting the code results in a measurable performance improvement, the reformatting is likely unnecessary.
    • Rephrasing or changing the grammar of comments.
  • Adopting a shiny new library: Using a new library (especially one that impacts our code in a fundamental way) is a decision that we make internally as a team. Please ask us first before undertaking such a task.

iOS 開発に貢献

ウィキペディア iOS アプリのコードベースについて、ボランティアの皆さんの貢献を歓迎します。

アプリの作業をされたかつての貢献者と現行の貢献者の皆さん、お疲れさまです。

ベータテスターになる

ベータテスターとして手を貸してくれる人は、testflight.apple.comを開いてください。

ベータテスターをやめたい場合は直接、TestFlight アプリで以下のようにテスト停止を手続きしてください。

  1. TestFlight アプリを開く
  2. Wikipedia app（ウィキペディア・アプリ）をクリック
  3. アプリページが開いたら、ページの最下部までスクロール
  4. 「Stop Testing」（テスト辞退）をクリック。

テストの再開は、同じリンクからいつでもどうぞ

テスターができること

簡単な作業を探すなら最初の作業向きを示す「good first task」というタグ付きの作業を見てください。 Phabricator のこちらのワークボード（workboard）を開くと、「good first task」タグ付きの作業のうち iOS で積み残したもの（backlog）を一覧にします。

難易度が高い作業を担当する準備が整ったなら、iOS のバックログに目を通し、バグ・バックログ （Bug Backlog）欄に残ったものから作業するものを選んでください。 iOS バックログに残るタスク類は全件、こちらのワークボードにまとめてあります。 タスクの状態が不明、もしくは詳細状態を知りたい場合は、ぜひコメントを書いて保存してもらうと、できるだけ速やかに返答するように努めます。

特定の作業が現存しない場合は、PRの査読に回せるように WikipediaApp バックログのフォームを利用し、Phabricator に新しいタスクを立ててください。 ウィキペディアのアプリ版リポジトリに加えた変更は全件、必ず Phabricator にタスクとして記録してください。 そうすると担当チームの 技術者や製品管理者を補佐して変更の評価を促し、財団のQA過程の一部として適切な査読を必ず受けると保証します。

変更の動機を説明してください。

  • 新しい機能ですか？ これはバグですか？
  • ウィキで議論された場合はリンクを付けてください。
  • 利用者体験に何らかの変更を期待するかしないか注記してください
  • 実施した変更の簡潔なまとめ。

担当するタスクを決めました。次は何を？

では担当チームにご自身が何に取り組んでいるか知らせましょう。

  1. Phabricator を開き、そのタスクの担当者をご自身に指定。
  2. そのタスクにはリリース用の「WikipediaApp」タグを付けます。 リリースボードの現況を探してチェック。 担当タスクにリリース名をタグ付けすると、リリースボードに追加されます。
  3. リリースボードを開いて、タスクを「Doing」列（実行中）に移項します。
  4. 開発を完了したら、そのタスクを「Needs Code Review」欄（コードレビュー待ち）に移項。

ボランティアの手で PR が立項したら、担当チームの技術者はできるだけ早くその PR を受領したと確認し、必要なら追加の指示を提供して、チームがパッチを査定できるように努めます。 これはできるだけ速やかに手を打つべきでありますがアプリ技術班は平日5-10日以内をめどにパッチ処理を承認するよう努力します。

作業の作成が完了するとトリアージュに進み、担当チームはトリアージュ済みの作業を適切なチームに送ります。 そのチームは次回のチームスプリントでまとめて評価。 当チームのスプリントは2週間かかり、理想上はフィードバックの1ラウンド目を28日以内に完了の予定。

ユーザから不可視の変更はチームのエンジニアが評価。 利用者に見える変更は、担当チームの製品管理者、設計者、技術者の査定を受けます。

  • 製品管理者は、変更案が担当チームの現在の優先機能または長期的な戦略に合致しているかどうか評価します。
  • 設計者は、変更案が担当チームの設計システムあるいは他の設計原則に 適合しているか評価します。
  • 技術者はコードレビューを提供して変更案のバグを除去し、担当チームのアーキテクチャとコード慣例に一致させ、ユーザ体験が劣らないようにします。

変更案は上記のいずれか、もしくはすべてからご意見ご指摘が届く可能性がありますから、 ボランティアの皆さんはそれらを受けるだろうと予測しておくことと、提出リクエスト（pull）に関して指摘された改善点 に対応するようお願いします。 提案された変更は申請書に組み込まれない可能性があるとあらかじめご了承ください。

PRを立てたのに、 GitHub でユニットテストが走らない。なんで？

ここではユニットテストの手順として、まずリポジトリの管理者が事前に手動で承認しないと走りません。 目的はセキュリティ保全のためです。 作業過程の承認においてセキュリティに懸念がある場合は、理由をお伝えするコメントを残します。

担当していたタスクから手を引きたい 。

タスクの担当中止（アサイン解除）と製品のバックログ "Tasks from Product Backlog" に戻せば、こちらのチームに辞退されたと伝わります。

自分の作業が受理されたと知らせは来る？

担当する作業が "Ready for PM Signoff"（プロジェクト管理者の承認待ち）という列に移動された場合は、ご自身の貢献された内容が次のリリースに組み込まれる見込みだと意味します。

ヒント

Phabricator を使うには

このようにコードを書きます

リポジトリ

ウィキペディア iOS 版アプリのコードは GitHub と Gerrit の両方にホストしてあります。

GitHub

こちらはメインのリポジトリで、財団の iOS 開発者はTestFlight（テストフライト）で公開ベータ版の作業とリリースを行います。 望ましい貢献方法 とはGitHub経由のプルリクエストです。


Contribute to Android development

The Wikipedia Android app is completely open-source and welcomes contributions from all. Our code repo is at github.com/wikimedia/apps-android-wikipedia.

Follow the steps below to get started, and feel free to ping any member of the WMF Android dev team (dbrant, cooltey) on phabricator for assistance.


Open bugs and feature requests

Work items are tracked on our work board. Unassigned tasks in the "Bug Backlog", "Tech Debt Backlog", and "Product Backlog" columns are generally suitable for development and roughly organized by descending priority. (Please do not work on tasks in other columns like "Open Questions" and "Needs Triage".)

Set up a development environment

Download the project source

If you plan on contributing to the project, you should create a fork of the repository into your own account, and checkout the fork. Otherwise you can simply checkout the code of our repository itself:

With SSH credentials (requires GitHub account): 

git clone git@github.com:wikimedia/apps-android-wikipedia.git

Or anonymously: 

git clone https://github.com/wikimedia/apps-android-wikipedia.git

Checkout and/or update any submodules within the project: 

git submodule update --init --recursive

Open in Android Studio

Open Android Studio, select "Open an existing Android Studio Project" from the main window, and select the repository folder from the file browser.

Important: If you are prompted about upgrades to components (e.g., Gradle or the Android Gradle plugin) during the initial build, please click "Don't remind me again for this project." We update these components in dedicated patches after a thorough review of the release notes, but they have a way of showing up in unrelated patches if automatic IDE prompting is enabled.

Make changes and submit for review via GitHub

git checkout -b Txxxxxx

Please ensure your PR has an associated phabricator ticket. All changes to Wikipedia app’s repositories should be captured in tasks on Phabricator. This aids the team's engineers and product managers to evaluate the change and ensures it is properly reviewed as part of our QA processes.

If a task does not currently exist, please create a new task for the PR on phabricator via the Android team backlog form. Describe the motivation for the change:

  • Is this a new feature? Is this a bug?
  • If there was any discussion on wiki, please include a link.
  • Note whether there is any expected change in the user experience
  • A brief summary of the changes made.


Make and commit your changes, and provide a commit message describing your changes. (Please ensure that the commit message includes line breaks for lines running over 75 characters.) If your work is associated with a specific task in Phabricator, please include, as the last line of the commit message, the following line:

Bug: Txxxxxx (where xxxxxx represents the number of the Phabricator task, e.g., T149500).

After creating your commit, if this is your first of submitting the changes to the branch, you may need to set the upstream to it. 

git push --set-upstream origin BRANCHNAME

Once the command is done above, you can simply use the following command when you are in the branch you've been working on. 

git push

Once the task has been created and triages the team will conduct a series of reviews during the next team sprint. Our team's sprints are two weeks long and the first round of feedback should ideally be completed in 28 days. You'll most likely receive requests to update and resubmit the patch. (It happens to all of us!) Make these changes locally and use git commit to submit your update changes, and make sure the commits are in the same branch.

After submitting a new branch to GitHub, you can create a Pull Request for other developers to review the changes. For more information, see Creating a pull request

Non-user facing changes will be reviewed by the team's engineers. User facing changes will be reviewed by the team’s product manager, designer AND engineers:

  • The product manager will assess whether the proposed change aligns with our team's current feature priorities or longer term strategy.
  • The designer will assess whether the proposed change aligns with our team's design system or other design principles.
  • The engineers will provide code review to ensure that the change is free from bugs, aligns with our architecture and coding conventions, and doesn’t result in a degraded user experience.

Proposed changes will likely receive feedback from any or all of the above and so volunteers must be prepared to receive those and be willing to act on suggested improvements to the pull request. Please be aware that it is possible that your proposed changes will not be accepted into the application.

Tip: To avoid CI test failures, it's a good idea to run checkstyle (./gradlew checkstyle) and the unit test suite (./gradlew testDevDebug or ./gradlew tDD) from the project root before pushing to GitHub.

Automated Tests

The codebase supports two kinds of tests:

  1. JVM JUnit (preferred, off device, fast, less flaky)
  2. Android instrumentation (on device)

Command line usage

  • JVM JUnit
    ./gradlew testDevDebug
  • Android instrumentation
    ./gradlew connectedDevDebugAndroidTest
  • Both JVM JUnit and Android instrumentation (including screenshot tests)
    ./gradlew testAllDevDebug
Tips
  • When running testAll*, add the --continue flag to run the Android instrumentation tests even if the JVM JUnit tests failed.

Android Studio setup

Both kinds of tests are supported in Android Studio. You may toggle between them by changing the Test Artifact from View -> Tool Windows -> Build Variants. "Unit Tests" are JVM JUnit tests and "Android Instrumentation Tests" are what it says. A run configuration must be made to prior to executing the tests.

Help make it better!

Pick a task from Phabricator:

Testing:

See pending/recent code reviews:

Tips

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.

Optimizing Gradle builds

The Gradle build system requires a notoriously large amount of system resources, but there are ways of speeding it up and making sure it works consistently. Add the following lines to your ~/.gradle/gradle.properties file: 

org.gradle.daemon=true                                                          
org.gradle.parallel=true
org.gradle.configureondemand=true
org.gradle.jvmargs=-Xmx2048M

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 assembleDevDebug

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

./gradlew -q assembleDevDebug

To install build on device/emulator: 

./gradlew -q installDevDebug

To see ProGuard output: 

./gradlew clean --info proguardDevRelease

To run Kotlin checkstyle: 

./gradlew ktlint

To run Lint: 

./gradlew lintDevDebug

To refresh dependencies (usually not needed): 

./gradlew --refresh-dependencies

To list dependencies: 

./gradlew app:dependencies --configuration compile

Developer Settings

When using the dev build variant the developer settings are enabled automatically. For other flavors you could tap 7 times on the Wikipedia globe on the About page. Once enabled, you can open the developer settings by accessing the app settings, then tap on the icon on the right in the top toolbar.

Advanced development and debugging

Working with Vagrant and the Content Service

  • To work with a local Vagrant instance, change the mediaWikiBaseUri developer setting and optionally disable mediaWikiBaseUriSupportsLangCode.
  • To work with a local RESTBase instance, update RESTBaseUriFormat and optionally enable useRestbase_setManually.
  • mediaWikiBaseUriSupportsLangCode controls whether the wiki language of mediaWikiBaseUri is prefixed.
  • mediaWikiBaseUri and mediaWikiBaseUriSupportsLangCode are the second argument of RESTBaseUriFormat.
  • useRestbase_setManually and useRestbase can affect whether a MediaWiki or RESTBase client is used internally. When a MediaWiki client is forced, RESTBaseUriFormat is unused.
  • The Wiktionary domain is currently hardcoded. Ex: http://localhost:6927/en.wiktionary.org/v1/page/definition/dog
  • It is recommend to fully terminate the app process after changing any of these settings.
Beta cluster config

Ex: 

RESTBaseUriFormat (default): %1$s://%2$s/api/rest_v1/
mediaWikiBaseUriSupportsLangCode (default): enabled
mediaWikiBaseUri (nondefault): https://wikipedia.beta.wmflabs.org
Local MediaWiki with production English Content Service config

Ex: 

RESTBaseUriFormat (nondefault): %1$s://en.wikipedia.org/api/rest_v1/
mediaWikiBaseUriSupportsLangCode (nondefault): disabled
mediaWikiBaseUri (nondefault): http://localhost:8080
Auth manager config
RESTBaseUriFormat (default): %1$s://%2$s/api/rest_v1/
mediaWikiBaseUriSupportsLangCode (nondefault): disabled
mediaWikiBaseUri (nondefault): http://authmanager.wmflabs.org
Local Content Service config (broken)

Ex: 

useRestbase_setManually (nondefault): enabled
useRestbase (default): enabled
RESTBaseUriFormat (nondefault): http://localhost:6927/%2$s/v1/
mediaWikiBaseUriSupportsLangCode (default): enabled
mediaWikiBaseUri (default): https://wikipedia.org

This doesn't quite work at moment. The app attempts to use a RESTBase feed/ endpoint when page/ is needed for the Content Service.

Local Vagrant with local Content Service config (broken)
useRestbase_setManually (nondefault): enabled
useRestbase (default): enabled
RESTBaseUriFormat (nondefault): http://localhost:6927/%2$s/v1/
mediaWikiBaseUriSupportsLangCode (nondefault): disabled
mediaWikiBaseUri (default): http://localhost:8080

This is currently broken for same reason the local Content Service config is.

Scripts

Setup
cd scripts
virtualenv -p python2 .env
. .env/bin/activate
pip install -r requirements.txt

Note: the lxml Python module seems to have system package dependencies on Debian and Ubuntu. If you're missing headers, try apt install libxml2-dev libxslt1-dev python-dev.

Troubleshooting Script Setup

On OS X a few of us ran into the issue that `libxml` couldn't get compiled. Running the following command helped: 

xcode-select --install

If this still doesn't work, you might also want to try: 

pip install sh jinja2 unicodecsv

This will produce output files under app/src/main/assets which will be included in the apk file.

Would like to try npm link with a local wikmedia-page-library repo? Please refer the [1] and then follow the steps above.

Update generated static data files
cd scripts
python generate_wiki_languages.py
python make-templates.py

Remote configuration

On startup, the app attempts to update its configuration by checking a JSON config file updated as part of the MobileApp extension. This remote configuration file is typically used for things like managing EventLogging sampling rates or rolling out new features incrementally.

On Wikimedia production wikis, as well as on the Beta Cluster or a local MediaWiki environment (such as MediaWiki-Vagrant) with the MobileApp extension, the file is located at: https://<host>/w/extensions/MobileApp/config/android.json

See T162164 for details on the treatment of static files in the Wikimedia production environment.

Purging the cached configuration (note: requires production shell access)

After a configuration update is deployed, making it available in production before the old version naturally expires out of cache will require a purge.

To do so: 

ssh tin
echo "https://meta.wikimedia.org/w/extensions/MobileApp/config/android.json" | mwscript purgeList.php --wiki=aawiki

String resource translations

The app's string resources are translated by the volunteer community at Translatewiki.net. See Translation of app string resources (and in particular the section TWN sync for Android) for details.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Wikimedia_Apps/Developing_for_the_apps/ja&oldid=8546374"