F-Droidにアプリを提出：クイックスタートのガイド

これは、F-Droid向けにアプリをパッケージ化するためのステップバイステップガイドです。アプリに関するメタデータのマージリクエストを直接提供でき、メンテナーの作業を簡単にできるため、リポジトリにアプリを追加する最善の方法と考えられています。

準備とコンプライアンスチェック

アプリケーションの収載を提案する前に、収載ポリシーへの準拠状況を慎重に確認する必要があります。以下は簡単なチェックリストです。

アプリには公開されたソースコードリポジトリとFOSSライセンスファイルが必要です。リポジトリには、プレースホルダーとしてのダミーファイルではなく、実際の最新ソースコードが含まれていることを確認してください。
アプリの依存関係はFOSSのみである必要があります。FirebaseやGMSは、受け入れられない非FOSSライブラリの代表的な例です。これらがなくてもアプリが何らかの形で動作する場合は、それらを含まないflavor/バージョンを作成してください。ビルドツールもFOSSである必要があります。プロプライエタリなIDEが必要な場合は、収載できません。いずれにしてもF-Droidはコマンドラインツールからビルドするため、ビルド手順があるとコントリビューターの助けになります。
アプリの作者に通知済みである必要があります（かつ、作者が収載に反対していないこと）。あなたが作者でない場合は、アプリのリポジトリでIssueを作成し、作者に許可を求めてください。
説明文用のメタデータファイルがリポジトリに追加されていること。これはいくつかのテキストファイルと画像からなる単純な構造であり、収載前に必ず追加する必要があります。フォルダー構造はFastlane/Triple-Tに従っていますが、実際のツールは必要ありません。

これらの要件をすべて満たしていれば、このアプリは収載の準備ができているはずです。

上流のメタデータ

アプリケーションの上流 Git リポジトリの各公式リリースコミットには、タグが必要です。たとえば、AndroidManifest にversionName: '1.0' が含まれている場合、そのコミットにはv1.0 タグが必要です。アプリケーションのソースリポジトリにもメタデータを追加することが強く推奨されます：

fastlane/metadata/android/en-US/short_description.txt（80文字未満、末尾のピリオドなし）
fastlane/metadata/android/en-US/full_description.txt
fastlane/metadata/android/en-US/images/icon.png
fastlane/metadata/android/en-US/images/phoneScreenshots/1.png
fastlane/metadata/android/en-US/images/phoneScreenshots/2.png

AndroidManifest に versionCode: 123 が含まれている場合は、このバージョンの新機能に対応する説明があるはずです。

fastlane/metadata/android/en-US/changelogs/123.txt（最大500文字）

F-Droidクライアントのメタデータのディレクトリで、実際の例を確認できます。

説明、グラフィック、スクリーンショットの他の形式とロケーションもサポートされています。たとえば、metadata/en-US ディレクトリは、代わりに fastlane/metadata/android/en-US にすることができます。

リポジトリにそれらのファイルがない場合は、アプリケーションの開発チームにマージリクエストを送信し、バージョンタグがない場合はIssueを作成してください。このメタデータを用意しておくことで、開発者が直接管理できるようになり、その更新や今後の翻訳が自動的に取り込まれます。

ビルドメタデータを理解する

公式F-Droidクライアントのビルドメタデータを例として見てみましょう。このファイルは https://gitlab.com/fdroid/fdroiddata/-/blob/master/metadata/org.fdroid.fdroid.yml にあります。fdroiddataリポジトリには、F-Droidメインリポジトリにあるすべてのアプリのビルドメタデータが、metadata フォルダー内に含まれています。fdroidserver は、これらのメタデータを処理し、ビルドを実行するために使用されます。メタデータのファイル名、つまり org.fdroid.fdroid は、アプリのApplication IDに対応しています。

メタデータの最初の部分は完全に説明的なもので、AntiFeatures、Categories、AuthorName、AuthorEmail、AuthorWebSite、License、WebSite、SourceCode、IssueTracker、Translation、Changelog、Donate、Liberapay、OpenCollective、Bitcoin、Litecoin が含まれます。これらの情報は、クライアントとウェブサイトに表示されます。

2つ目の部分は、APKのビルド方法を制御します。これには以下が含まれます:

RepoType と Repo。ソースコードのVCSメタデータ
Builds。ビルドブロックの一覧で、各ブロックはビルド済みまたは今後ビルドされるAPKに対応します
Binaries と AllowedAPKSigningKeys。再現性のあるビルドの参照バイナリに関するメタデータ

Builds に新しいビルドブロックがあると、fdroidserver はそれに従ってビルドを開始します。たとえば、次のビルドブロックはそのようなプロセスを定義します:

  - versionName: 1.23.2 versionCode: 1023052 commit:
    0ea06b1c1d68765c4a434d0b676b3e0f23f04cb1 subdir: app gradle:
      - full
    scandelete:
      - app/src/androidTest/assets
      - app/src/test/resources
      - libs/sharedTest/src/main/assets
      - libs/index/src/commonTest/resources
    gradleprops:
      - strict.release

まず、ソースコードが Repo からクローンされます。次に、commit がチェックアウトされます。作業ディレクトリは app に設定されます。ビルド前に、スキャナーがソースコードに対して実行され、scandelete で定義されたパス内のバイナリファイルが削除されます。その後、fdroidserver はGradleコマンドを実行してアプリをビルドします:

  gradle assembleFullRelease -Pstrict.release

APKはGradleプロジェクトのデフォルトパスで見つかり、正しい versionName と versionCode を持っていることが確認されます。最後に、このAPKは署名され、他のAPKとともに公開されます。

最後の部分は、AutoUpdateMode、UpdateCheckMode、UpdateCheckIgnore、VercodeOperation、UpdateCheckName、UpdateCheckData、CurrentVersion、CurrentVersionCode など、アプリをどのように更新するかに関するものです。checkupdates runnerは毎日実行され、リポジトリをチェックして新しいバージョンを探します。新しいバージョンがある場合、メタデータが更新され、merge requestが作成されます。

ビルドメタデータの各フィールドに関する詳細は、Build Metadata Reference と Repository Style Guide で確認できます。

Gradleアプリのビルドメタデータを書く

以下の手順では、アプリのApplication IDが com.example であると仮定します。アプリには、自分のドメイン名に対応する一意のIDを使用してください。fdroiddata をフォークし、リポジトリをクローンして、masterから新しいブランチを作成します。例：com.example。詳しくは https://gitlab.com/fdroid/fdroiddata/-/blob/master/CONTRIBUTING.md を参照してください。メタデータを書くときは、fdroidserverをインストールしておくこともおすすめします。メタデータのフォーマットやlintに役立ちます。metadata/com.example.yml にメタデータファイルを作成します。エディターで開き、メタデータを書き始めましょう。テンプレートから始めることもできます。ビルドメタデータファイルは何千もあるため、通常は自分のメタデータのベースとして使える、似たビルドメタデータを見つけられます。たとえば、アプリがFlutterを使用している場合は、fdroiddata リポジトリ内でFlutterアプリを検索できます。templates フォルダーにも例があります。また、fdroid import を使用して、fdroidserver でテンプレートを生成することもできます。

これで、空のメタデータファイルまたは簡単なテンプレートが用意できました。ユーザーがアプリとその作者についてよりよく理解できるよう、できるだけ多くの説明情報を提供してください。

次に、Repo 情報と Builds 内のビルドブロックを追加します。Gradleアプリでは、これは簡単です。また、Flutterなどの一般的なツールチェーンもテンプレートで対応しています。アプリが他のツールチェーンでビルドされていて、fdroiddata 内に例が見つからない場合は、sudo、prebuild、build を使って、すべてのビルド手順を手動で定義できます。fdroidserver がAPKを見つけられるように、output を設定する必要があります。

自動更新の設定

更新を手動で管理する特別な理由がない限り、自動更新を設定することをおすすめします。これにより、F-Droidのメンテナーとあなたの双方にとって、メンテナンスの手間を減らせます。自動更新を有効にすると、バージョンを上げて新しいリリースにタグを付けるだけで済みます。F-Droidはリポジトリを定期的にチェックし、新しいバージョンが見つかるとメタデータを更新します。versionNameとversionCodeが通常の場所、つまりandroidブロックまたはAndroidManifest.xmlにあるGradleアプリでは、特別な設定は必要ありません。ただし、バージョン情報を別の場所に置いている場合は、UpdateCheckDataを使って抽出する必要があります。F-Droidは正規表現を使って抽出するだけで、Gradleコードは実行しないため、バージョン情報を動的に組み立てたり計算したりすることはできません。

ABI分割を設定する

ABI分割の設定は必須ではありませんが、APKが大きく、ABI分割によってAPKサイズを効果的に削減できる場合は、設定することを強くおすすめします。

現在、ABI分割に対する特別なサポートはありません。そのため、各APKはそれぞれ別のビルドブロックとして追加し、異なるバージョンコードとビルド手順を指定する必要があります。異なる Gradleフレーバーやプロパティを使って、別々のネイティブライブラリをビルドできます。また、 prebuildでコードにパッチを当ててABIを制御することもできます。これらの異なるABI向けAPKは、 1つずつビルドされます。異なるABIのバージョンコードは、特別に設定する必要がある点に注意してください。F-Droidクライアントは常に、端末にインストール可能なAPKのうち、最も高いバージョンコードを持つものへアプリを更新します。そのため、通常はバージョンコードが次の順序になるようにします: armeabi-v7a < arm64-v8a < x86 < x86_64。 fdroidserver は repo内に最も高いバージョンコードのAPKだけを保持し、それ以外は archiveへ移動するため、新しいバージョンのバージョンコードは、古いバージョンのバージョンコードより高くする必要があります。言い換えると、ABIを表す桁はバージョンコードの最下位に置く必要があります。バージョンコードを計算するには、VercodeOperationを設定する必要があります。例:

VercodeOperation:
  - 10 * %c + 1
  - 10 * %c + 2
  - 10 * %c + 3
  - 10 * %c + 4

再現可能ビルドを設定する

再現可能ビルドは、F-Droidでアプリを公開するための必須要件ではありません。ただし、F-Droidではその利用をベストプラクティスと考えています。残念ながら、後から簡単に切り替えることはできません。Androidでは異なる署名鍵による更新が許可されていないため、ユーザーが再インストールする必要があるからです。そのため、主に新しいアプリでの利用を推奨しています。

再現可能ビルドのポイントは、開発者が公開したAPKの署名によって、F-Droid側のビルドが開発者のビルドと同一であること、つまり本来含まれるべきでないものが含まれていないことを保証できる点にあります。同時に、F-Droidのビルドサーバーは、開発者のビルドが公開されているソースコードと一致していること、つまりこちらにも本来含まれるべきでないものが含まれていないことを検証します。

これにより信頼性が高まり、サプライチェーン攻撃も難しくなります。また、F-Droid版だけにバグが存在する、またはその逆の状況も起こり得なくなります。開発者の鍵を使うことで、何らかの理由でF-Droid側が一時的に更新を提供できない場合でも、開発者自身がユーザーに更新を提供するという選択肢を持てます。

一部のアプリ、特にネイティブコードを含まず、Kotlin/Javaのみを使用しているアプリは、再現可能にするのが非常に簡単です。一方で、より多くの作業が必要になるアプリもあります。残念ながら、まったく再現可能にできないアプリもあります。

さまざまな利点を考えれば、少なくともアプリを再現可能にすることを試みる価値はある、という点に開発者が同意してくれることを願っています。ただし、そのために時間やリソースを割くことができない、または割きたくない場合は、もちろんその判断を尊重します。

詳しくは、以下を参照してください:

メタデータをテストする

初期のビルドメタデータは、期待どおりに動作しない場合があります。そのため、テストが必要です。 fdroidserver がインストールされている場合は、fdroid lint <appid>を実行して一般的な問題に関するヒントを確認し、fdroid rewritemeta <appid>を実行してメタデータファイルを整形します。その後、そのメタデータを使ってAPKのビルドを試すことができます。難しい方法で進めたい場合は、ローカルでビルドを実行する方法について、ドキュメントを読んでください。代わりに、 F-DroidのCIを使えば、メタデータを簡単にテストできます。変更をコミットして自分のフォークにプッシュしてください。パイプラインは自動的にトリガーされます。すべてのパイプラインが成功すれば、おめでとうございます。これで動作するビルドメタデータができました。一部のパイプラインが失敗した場合は、ログを読み、それに応じてメタデータを修正してください。

ビルド環境

2022年2月にUbuntu 21.10を搭載したノートPCで試したところ、F-Droidビルド環境のセットアップには2GBの通信量と5GBのディスク容量が必要でした。

ネットワークの要件：

60MB： fdroiddata と fdroidserver の最新の状態のclone
75MB： docker.io のインストール
1000MB: コンテナーを読み込む
800MB: ビルド

保存領域の要件：

1000MB：レポジトリのcloneと docker.io のインストール
4000MB: コンテナーを読み込んでビルド

サーバーツールコンテナーの最新バージョンをダウンロードして起動します:

git clone --depth=1 https://gitlab.com/fdroid/fdroidserver ~/fdroidserver
sudo sh -c 'apt-get update &&apt-get install -y docker.io'
sudo docker run --rm -itu vagrant --entrypoint /bin/bash \
  -v ~/fdroiddata:/build:z \
  -v ~/fdroidserver:/home/vagrant/fdroidserver:Z \
  registry.gitlab.com/fdroid/fdroidserver:buildserver

コンテナー内で:

. /etc/profile
export PATH="$fdroidserver:$PATH" PYTHONPATH="$fdroidserver"
export JAVA_HOME=$(java -XshowSettings:properties -version 2>&1 > /dev/null | grep 'java.home' | awk -F'=' '{print $2}' | tr -d ' ')
cd /build
fdroid readmeta
fdroid rewritemeta com.example
fdroid checkupdates --allow-dirty com.example
fdroid lint com.example
fdroid build com.example

fdroid readmeta などのコマンドがエラーを返す場合は、それに応じて ~/fdroiddata/metadata/com.example.yml を編集し、もう一度コマンドを実行してみてください。ビルドが成功したら、コンテナーを終了し、New App ラベルを付けてメタデータファイルをコミットして、forkにpushします:

exit
cd ~/fdroiddata
git add metadata/com.example.yml
git commit -m "New App: com.example"
git push origin com.example

fdroiddata リポジトリで、あなたの com.example ソースブランチを選択してマージリクエストを作成します。パッケージャーがマージリクエストを確認するまで待ってください。質問された場合は内容を確認し、できるだけ早く返信してください。

トラブルシューティング

IRC、Matrix、XMPP、メール、その他のチャンネルを通じて、F-Droidに関するサポートを受けることができます。

アプリケーション審査プロセス

収載提案が提出されると、アプリケーションはレビュー工程に入ります。F-Droidスタッフがアプリケーションのソースコードを確認し、収載に適しているかどうかを判断します。適していない場合は、収載できるようにするために必要な手順をすべて判断します。

F-Droidは、ユーザーに自由ソフトウェアを提供することを約束するソフトウェアリポジトリであるため、審査プロセスは、F-Droidのメインリポジトリから配布されるすべてのアプリケーションが自由ソフトウェアであることを確認するためにあります。

これは、レビュアーが行うことの一部を示したリストです:

F-Droidスタッフはあなたのソースコードリポジトリにアクセスし、提案されたアプリケーションが認められている自由ソフトウェアライセンスまたはOSIライセンスの下で公開されていることを確認するため、README を含むライセンスファイル内の著作権表示を探します。
レビュアーは、使用しているビルドシステムと、F-Droidビルドサーバーがそれを処理できるかどうかを確認するために、ビルドスクリプトを調べます（AntとGradleが最も一般的で、扱いやすいものです）。
レビュアーは、ソースコードのコピーをダウンロードしようとします。
レビュアーは、すべてのソースコードファイルを確認し、それぞれのライセンスが対応するlicense/READMEファイルと一致しているかを検証します。
レビュアーは、アプリケーションが事前コンパイル済みライブラリやバイナリblobを使用していないか確認します。
レビュアーは、アプリケーションで使用されている非フリーリソースを特定するために、ソースコード以外のファイルを確認します。
F-Droidスタッフはソースコードにひと通り目を通し、あなたのアプリケーションが非フリーな依存関係を使用していないか、広告を表示していないか、ユーザーを追跡していないか、非フリーまたは変更不能なサービスやアプリケーションを宣伝またはそれに依存していないか、ユーザーに有害または望ましくないことを行っていないかを確認します。
レビュアーは、アプリケーション内の AntiFeatures の概要を一覧にします。
レビュアーは、サードパーティ製のプロプライエタリソフトウェアの使用を取り除くために、アプリケーションへのパッチ適用を試みます（該当するものがある場合）。
F-Droidスタッフは、あなたのアプリケーションに適した更新プロセスを判断しようとします。たとえば、リリースがVCSタグや AndroidManifest.xml、build.gradle.kts、pubspec.yaml、その他の場所にあるバージョン情報とどのように対応しているかを確認します。
レビュアーは、アプリケーションに適したメタデータファイルの作成を試み、それをローカルのF-Droidビルドサーバーインスタンスに追加します（fdroid rewritemeta と fdroid lint は、メタデータが正しい形式になっていることを確認するために使用されます）。
レビュアーは、分離された環境でアプリケーションのビルドを試み、そのプロセスが成功し、機能するAPKが生成されるかを確認します。
通常はGitLab CIが使用されますが、ランナーが提供できる以上のリソース (ストレージ、メモリ、時間) を必要とするアプリでは、メタデータの準備とテストにローカルマシンを使用する場合があります。
すべてが順調に進めば、F-Droidスタッフはローカルの fdroiddata Gitリポジトリに新しいメタデータファイルを追加し、その変更をGitLabに同期します。

アプリケーションが審査の一部の手順で不合格になった場合、提案が投稿された元のsubmission queueスレッドでフィードバックが提供されます。

GitLab上の fdroiddata リポジトリが更新されると、あとはF-Droidの公式ビルドサーバーがアプリケーションを取得、ビルドし、メインのF-Droidリポジトリで公開するのを待つだけです。

GitLabの fdroiddata リビジョン履歴を確認することで、アプリケーションが収載されたことを確認できます。

ビルドプロセス

アプリケーションのメタデータが fdroiddata GitLabリポジトリに追加された後、次のステップでは、メインのF-Droidビルドサーバーがアプリケーションのソースコードと関連コンポーネントを取得し、アプリケーションをビルドして、メインのF-Droidリポジトリで公開します。

このビルドプロセスはスケジュールに従って実行されるものではなく、前回のサイクルが公開された後に新しいサイクルが開始されます。アプリケーションは一括で処理されます (平均的な頻度は、過去のサイクルを見ることで推測できます)。各手順は裏側で実行され、ほとんどが自動化されているため、提出者がする必要があるのは完了を待つことだけです。

1つのアプリケーションに対するビルドプロセスが成功した記録は、そのアプリ専用のF-Droidウェブサイトページで提供されます。たとえば、F-Droidクライアントのビルドログを参照してください。

失敗したアプリのログは、ビルドサイクル中であれば F-Droid Monitor - Running ページで、前回のサイクルであれば Build ページで確認できます。これは、ビルドが予期せず失敗した場合に、問題の診断に役立ちます。

想定されること

アプリケーションのメタデータが承認され、GitLab上の fdroiddata Gitリポジトリに受け入れられても、メインのF-Droidリポジトリにすぐに表示されるわけではありません。

アプリケーションにビルド上の問題がなければ、fdroiddata のマージからアプリケーションがメインリポジトリに表示されるまで、およそ24〜48時間かかります。1 この時間的な制約は、ビルドプロセスのAPK署名部分に起因します。キーストアへのアクセス手順で人による対応が必要になるためです。2

公開後、アプリはすぐにリポジトリで利用可能になり、どのクライアントでも更新またはインストールできるようになります。f-droid.orgウェブサイトでは、更新されたアプリや新しいアプリについて、すべての言語のページを生成するのに時間がかかるため、更新が反映されるまで少し遅れがあります。

外部リンク

F-Droidアプリケーションsubmission queue on GitLab（新規申請用）
フォーラム上のF-Droidアプリケーションsubmission queue（古い申請のフォローアップ用）
fdroiddata GitLabリポジトリ
fdroiddata リビジョン履歴