始める

From The Document Foundation Wiki
Jump to: navigation, search
本ページはGlobal Wikiからの有志による翻訳ページです。未翻訳があることや内容が古い場合があります。最新化、翻訳にご協力お願いします。
日本語独自の情報についてまとめることを目的として、日本語コミュニティによって運営されているページとして 日本語コミュニティ独自ページ があります。
URLが wiki.documentfoundation.org/JA で始まっていて、カテゴリーがJAのページです。
そちらもご利用ください。

注意:このページのオリジナルは英語版 始める2017-11-01T18:27:27‎ の版からコピーしたものです。

原文は逐次改定されるので、定期的に原文を参照して差分を更新し、ずれることがないようにお願いします。なお差分更新をかけた場合は上の日付も修正しておいてください。


開発者とユーザはLibreOfficeの開発に様々な方法で貢献することができ、誰もがこのプロジェクトに歓迎されています。

ユーザは例えば、以下のようなことで開発の補助ができます: ベータ版のテストや、バグの報告と検証ドキュメントの作成テンプレートへの貢献シソーラスや辞書の更新あなたの母国語への翻訳画像の追加LibreOfficeの広報活動

このページは開発者のためのものです。私たちはすべてのレベルの開発者にオープンであり、"コア"な開発者(これは基本的に開発が始まった頃から携わっている人たちを表す)は少数ですが、多くは比較的新しく加わった人たちであることを覚えておいてください。LibreOfficeはもっとも大きく、もっとも歴史があり、(OpenOfficeと同じくらい)もっともよく知られたフリーソフトウェアパッケージの一つです。もしあなたが学生だったり開発職を探しているのであれば、「私はLibreOfficeのために作業している」と履歴書に書けることは大きなプラスになります。同意の後、私たちのDevelopment Mentoring Leadを参考資料に使うことができます。開発者はLibreOfficeのコードベースを改善する手助けになります。最初は巨大なコードベースに圧倒されるかもしれませんが、ドキュメントは改善されていくので、既存の開発チームの手助けを受けることができるでしょう。このページではあなたの最初のパッチを提出する手助けになるでしょう。

全体像をつかむには (すべてのeasyHacksにはコードポインタがあることを覚えておいてください):

新しい開発者のためのステップ・バイ・ステップ・ガイド

LibreOfficeのサイズや複雑さで簡単に圧倒されてしまうでしょう。ソースは多くのプログラミング言語やフォーマットで書かれています — C, C++, Java, Bash, JavaScript, Python, Perl, SQL, Test, XML — そして約102,000ファイル (すべてのローカライゼーションを除く) で、36,000,000行(ソースコードは7,000,000行)のソースコードで成り立っています。

誰もが全てのコードを詳しくは理解できませんが、コードの一部を詳細に知っている多くのコアな開発者がいます。このステップ・バイ・ステップ・ガイドでは「貢献したい」から、めでたく最初のパッチがmasterにマージされるまでの簡単な道筋を示します。もしヘルプやもっと情報が必要であれば、気軽に私たちに連絡してください: Development mentor


コミュニケーションチャンネルへの接続

わたしたちのメインのコミュニケーションチャンネルは libreoffice@lists.freedesktop.org です。ここに参加することを推奨しています。また、このリストをフォローすることもできます: http://nabble.documentfoundation.org 開発者メーリングリストの使い方はこちら

わたしたちはソースコードが誰にでも自由に使える状態を保つことを望んでおり、それゆえにライセンス宣言を libreoffice@lists.freedesktop.org にメールしていただくことが重要です(件名は <your name> license statement でお願いします)。本文は次のとおりにしてください:

   All of my past & future contributions to LibreOffice may be
   licensed under the MPLv2/LGPLv3+ dual license.

意図が明確であれば、多少の言い回しの違いは大丈夫です。送信後、歓迎のメッセージが返信されます。また、わたしたちは開発者リスト を wiki に保持しています。

もし簡単な質問にすぐ返信が必要であれば、わたしたちをIRC freenode #libreoffice-dev connect via webchatで探すことも可能です。

LibreOfficeのビルド

開発を行うために、ソースコードのローカルコピーが必要です。コードは全てgitで管理されています。

Windows

Windowsでの開発者はCygwinとほかのユーティリティのインストールが必要です。簡単な方法は lode を使うことです。

Windowsでディレクトリ名の問題(LibreOfficeがmscvc.exeを見つけられない、といった類)が生じることがあることに気をつけてください。こちらもご確認ください:

パスの問題の修正


アンチウイルスソフトに関して

ビルド時にはアンチウイルスソフトの無効化を強く推奨します(もちろん無効化している間にはネットサーフィンをしないこと)。

もしアンチウイルスソフトを有効にしたままにするのであれば、必ず少なくとも以下のものを例外リストに追加してください:

  • perl.exes
  • <git home>/workdir

そうしないと、ビルドに失敗します。なお、ビルド中にアンチウイルスソフトが動作していると、たいていビルド時間が伸び、ときどき30%程度も伸びることがあります。

動作中のアプリケーションのリアルタイム保護が問題になるケースもあります。アンチウイルスソフトが動作しているアプリケーションをスキャンすることことによって、コンパイルして新しい(同じテスト名の)テストツールを生成するときに、リンカがファイルに書き込めないことがあります。アンチウイルスソフトがこのファイルをブロックしてしまうためです。また、テストツールが動いている間はアンチウイルスソフトも遅くなります。

インストール中にアンチウイルスソフトに関連するいくつかの問題が報告されているため、lodeを実行中はアンチウイルスソフトの無効化を強く推奨しています。

macOS

macOSでは(あなたが複雑なセットアップ方法に精通しているならば)様々な方法でセットアップできますが、始めるにあたってはこちらがおすすめです: 準備済みのクイックセットアップ

Linux

Linux(多くのディストリビューション)ではパッケージインストーラでセットアップすることができます。こちらがおすすめです: Linuxでのビルド

パッチを送る準備

LibreOfficeがコンパイルできたら、パッチを送る準備は出来ています。わたしたちは gerrit を使ってパッチの追跡をしていますので、ここで新しいアカウントを作成する必要があります。こちらに従ってください: gerritセットアップガイド

基本的にパッチの送信/作業には2つの方法があります。Git reviewに精通している方はこれをつかうこともできますが、logerritという簡単なツールを使うことを推奨しています。

logerritスクリプトが使用できずにgerritのフックが動作しないような、ヘルプ(や、クローンしているだけのヘルプ)などのサブモジュールへの変更をコミットするときには気をつけてください。 セットアップの方法はDevelopment/Submodulesをご覧下さい.


直したい最初のバグを見つけましょう

おめでとうございます!楽しい部分にきました。

最初のバグを直すことには、新たなツールや方法を学ぶことも含まれます。そのため、Easy Hacksと呼ばれる簡単なバグを区別しています。わたしたちはbugzilla(アカウント作成が必要)を使用して、報告されたバグの追跡を行っています。

Easy hacksは実際にバグですが、コアな開発者はバグの解決が容易になるように、ソースコードにポインタを追加したり、さらにときどき単にバグを解決する代わりに簡単な手引きの文章を追加したりします。 あなたに関係するプログラミング言語やスキルプログラミング言語は上も参照)からバグを選んでください。 見ての通り選択肢はたくさんあります。 「どうするか」に集中できるように、カテゴリ"Skill level: beginner"の中から選ぶことをおすすめします。

直すべきバグを選んだら、あなたがそのバグの作業をしていることがほかの人にわかるように、忘れずにbugzillaで自分に割り当ててください。 もし一般的なバグ(例えばfooからxyzへの変換のような)に対して作業を行いたいならば、割り当ては行わないでください。多くの人が並行して作業できるようにするためです。 しばらくして進捗がないなら割り当てを外せるようにEasyHacksはモニタリングされています。

もちろん後々行えるような手応えのあるものもあります:


バグの解消

経験上従うことを推奨する実用的なアドバイス:

  • masterのコピーに変更を加えないこと - 代わりにブランチを作りましょう
  • バグごとに別々のブランチを切り、バグフィックスがマージされるまでそのブランチを削除しないこと
  • コードスタイルにしたがうこと(変数の命名則など)
  • 新しいファイルを作ったら、ライセンスヘッダを使ってください。
  • 当面はコードの大きな再整形(reformatting)は避けてください(以下のリストのタスクを除く) - わたしたちはそのための自動あるいは特別な方法を中長期的に計画しています。
  • 新しいバグについて始める前にmasterを更新してください(そして何か変更を加える前にmake checkを実行して、きちんとコンパイルできることを確認してください)
  • 指示されていない限り、他人との間でパッチを送信し合わないでください。パッチがマージできなくなる恐れがあります。
  • パッチがマージされる準備が整っていないならば、査読者に作業中であることを知らせるため、(code-reviewに)-2を割り当ててください。
  • 我慢が重要です。査読には時間がかかり、またわたしたちは皆ボランティアなので、査読完了まで数日かかることが予想されます。

提案しているワークフロー

1. masterを更新する

あなたのmasterブランチが更新され動くことを確かめてください。masterブランチががあまりに古いと、パッチをマージできなくなる恐れがあります。

原則として、この場合に以下のコマンドを使ってください:

  • あなたのmasterが最新から1週間以上遅れている場合
  • 新たなバグフィックスが、マージされたばかりのブランチに依存する場合
./g pull -r
make
make check

!! make must be 3.8.1 or higher.

-rスイッチを使ってください。これは単にpullする以上にはるかに効果的です。また、masterはよく壊れますが、普通は短い間だけです(コミッターは普通間違ったコミットを行った場合に、すぐに対応します)。

makeが完了すると作業masterがあることから、もしパッチのコンパイル中にmakeに失敗するならばあなたのコードのどこかに原因があります。make checkではすべてのテストケースを実行し、LibreOfficeの作業バージョンがあることを確認します。

2. ブランチに入る

後であなたのパッチを変更するように言われるかもしれませんが、独立したブランチを作成してそこで作業すればとても簡単になります。あなたが作業するバグごとに新しいブランチ(masterから分岐)を作成してください。一度パッチがマージされたらブランチを削除できます。

git checkout -b test1

test1は適当な名前に読み替えてください。

3. バグを解決する

問題を特定し、コードを修正し、新たなバージョンを作成・検証してください。問題が解決されたことを確かめるため、可能な限りいつでもユニットテストを忘れずに行ってください。

手助けになる手軽なツールがいくつかあります。

定期的にgit commit -aを実行することを忘れずに。これによって、作業中間違えたときに簡単に戻すことができます。

4. パッチを送る

コミットメッセージは以下のようなものを推奨しています:

   tdf#12345 <short developer description of change, not just the bug title>
   <empty line>
   <description of what the patch does, the more words the better others understand it later>
  • もしコミットに関連したバグレポートがあれば、tdf#12345のようなバグへの参照を1行めに必ず入れてください。(詳細は後述)
  • 1行めの残りには変更点の簡単な要約を入れてください。この行の最大文字数は72文字です。
  • 現在形を使ってください。どう変えたのかを書いてください。簡潔に。ダッシュやブラケットのような、スペースを無駄にする「装飾」は避けてください。
  • 1行めに収まらないほどの説明が必要であれば、必ず2行めを空行にして、
  • 3行め以降にパッチの目的と何を行うのかを、(1行めの説明で)明確でなければどのように行うのかも書いてください。3行め以降は1行あたり80文字が上限です。コメントが長い時には適宜改行してください。ここには、変更前のコードがどのようにして正しく動かなかったのかも書くことができます。

もしあなたのパッチがBugzillaですでにまとめられているバグを修正するものであれば、コミットメッセージをトリガーとする自動バグ通知を受け取ることができます:もしコミットメッセージの1行めにtdf#12345といった形式でバグへの参照があれば、リポジトリに変更がpushされた時に関連するコメントが自動的にバグレポートに追加されます。詳細は mail-archive.comfdo-listarchive のアナウンススレッドを参照してください。

あなたの変更した内容が自動テストで壊れないことを確認してください;

make check

大丈夫であれば、パッチをgerritに送信することができます(パッチを送る準備を参照):

./logerrit submit master

パッチの査読

あなたのパッチはふつう1〜2日で査読されます。gerrit で進捗を追うことができ、変更があるたびにメールが送られます。(もしJenkinsがWindowsビルドのみ自動コンパイルに失敗すると報告してもあまり気にしないでください)

査読では一般に3つのことが起こります: In general 3 things can happen in the review:

  • コミッターがパッチが正しく動くことを査読・検証したら、masterにマージされます(おめでとうございます)
  • あなたが確認すべきコメントをコミッターが書き込みます
  • 時々パッチが他の機能を破壊し、「マージ不能」とマークされます

後ろ2つのケースになったら、あなたはパッチを更新する必要があります。

Code-ReviewVerified について

Gerritでパッチを見ると、以下の2つのステータスコードがあります:

  • Code-Review
  • Verified

査読者とCIシステム(jenkins)、さらに潜在的にはあなたはこれらのフィールドをパッチの状況のために使うことになります。

Code-Review

-2, -1, 0, +1, +2 が割り当てられます

-2 は作者が使用し、「作業中」であることを示すためのものです。-2ではパッチがマージされず、-2をつけた人のみがパッチを削除できます。

もし大きなパッチを作業するのであれば、パッチのアップロードは大いに歓迎されますので、-2にマークして、すべてのプラットフォームで正常にビルドできることを確認してください。

-1 は査読者が使用し、パッチの変更が必要であることを示します。

0 はコメントをつける時に使用し、パッチのマージの可否に影響しません。

+1 は査読者が使用し、パッチはOKだが、査読者に代替案があることを示します。

+2 は作者が使用し、査読不要であることを示します(これはコアな開発者のみが行うことができ、また注意深く使用されるべきです)。 あなたのパッチをマージする人は、マージ前に+2を使用するでしょう。+2のみがマージ可能であるためです。+2に設定できるかどうかは査読者のpush権限に依存します。この権限は個人個人に与えられます。

注意:-1が付いていたり、-2で応答がない限り、パッチはマージされません。


Verified

-1, 0, +1 が割り当てられます

-1 はCIシステムがビルドに失敗したことを示します(注意:必ずしもあなたのパッチに問題があるわけではなく、masterが壊れていることもあります)

-1 は査読者が使用し、期待された結果が再現できないことを示します。

0 はコメントをつける時に使用し、パッチのマージの可否に影響しません。

+1 はCIシステムがビルドに成功したことを示します。

+1 は査読者が使用し、期待された結果が再現できたことを示します。

注意:CIシステムが正常にビルドできない限り、パッチはマージされません。

パッチの更新

ブランチをチェックアウトし、

git checkout test1

必要な変更を加えそれらを検証してください。変更したくないコードの行番号やコミッターに賛同できない点をコメントすることは礼儀正しい行為です。これはgerritで直接行います。

再度コミットできる準備ができたら、--amendを使うことが重要です。

git commit --amend -a

重要 gerritパッチIDが消えるため、-mパラメータは使わないでください。gitを編集者にオープンにしており、コミットメッセージの編集が認められています(変更しないのも可)。編集時にはパッチIDが入った最後の行を消したり変更したりしないように注意してください。

これは(新しい変更IDで)新たなパッチを作成する代わりに、確実にパッチを更新するためのものです。

gerritに新しいパッチセットをアップロードしてください。

./logerrit submit master

おめでとうございます

あなたは、世界で最も人気のオープンソースパッケージに、無事に変更を加えることができました。

パッチの作成を続けていれば、すぐにコミッターになれます。