始める

    From The Document Foundation Wiki
    This page is a translated version of the page Development/GetInvolved and the translation is 74% complete.


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

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

    このページは開発者のためのものです。私たちはすべてのレベルの開発者にオープンです。LibreOfficeはもっとも大きく、もっとも歴史があり、(OpenOfficeと同じくらい)もっともよく知られたフリーソフトウェアパッケージの一つです。もしあなたが学生だったり開発職を探しているのであれば、「私はLibreOfficeのために作業している」と履歴書に書けることは大きなプラスになります。 開発者はLibreOfficeのコードベースの改善を支援できます。最初は巨大なコードベースに圧倒されるかもしれませんが、ドキュメントは改善されていきますし、既存の開発チームの手助けを受けることもできます。このページはあなたの最初のパッチを提出するようお手伝いします。全体像をつかむには:

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

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

    コード全体を詳細に理解している人はいませんが、コードの一部に詳しい、多くのコア開発者がいます。このステップ・バイ・ステップ・ガイドでは「貢献したい」から、めでたく最初のパッチがmasterにマージされるまでの簡単な道筋を示します。

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

    わたしたちのメーリングリストは libreoffice@lists.freedesktop.org です。これを購読することを推奨しています。オンラインで読むこともできます

    リアルタイムなチャットには、Libera Chatネットワーク上でIRC#libreoffice-dev IRC://を使用します。

    LibreOfficeのビルド

    開発を行うためには、ソースコードのローカルコピーが必要です。コードは全てgitで管理されています。ソースコードのクローン方法は、各OSでのビルド方法を記載した記事で説明しています。

    Windows

    Windowsでの開発者はCygwinとほかのユーティリティのインストールが必要です。もっとも簡単な方法は LODE (LibreOffice Development Environment) を使うことです。詳細なWindowsビルドの手引きも存在します。

    macOS

    LODE (LibreOffice Development Environment )の利用を推奨します。Xcodeについてのさらなる情報および詳細はこちらの記事 macOS上でのLibreOfficeのビルド をご覧ください。

    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 は3.8.1以降が必要です。

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

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

    2. ブランチに入る

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

    git checkout -b test1 origin/master

    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


    パッチの査読

    Easy Hacksの場合は、コードを提供した方をパッチのレビュアーとして追加します。パッチに変更があるたびにメールが送られます。

    査読では一般に3つのことが起こります:

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

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

    For more on the patch review process, see Development/gerrit/PatchReview.

    パッチの更新

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

    git checkout test1

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

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

    git commit --amend -a

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

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

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

    ./logerrit submit master

    ライセンス宣言

    わたしたちはソースコードが誰にでも自由に使える状態を保つことを望んでおり、それゆえにライセンス宣言を 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.
    

    It is important to make sure that the mail allows connecting the statement to the contributions, so send the statement from the same email that is used in your commits.

    意図が明確であれば、多少の言い回しの違いは大丈夫です。また、わたしたちは開発者リスト を wiki に保持しています。

    Please only send the statement no earlier than when you post your first submission to gerrit. If you are underage, ask your parents or legal guardians to send the email (all persons having guardianship).

    ソフトウェアに含まれるアートワーク(アイコンなど)を寄贈する場合は、ライセンス宣言の電子メールにこの内容を追加してください。

       Additionally, to the extent possible under law, I waive all
       copyright and related or neighboring rights to my past & future
       Artwork and Design contributions to the LibreOffice project, and
       similarly to The Document Foundation, placing such contributions
       under CC0: https://creativecommons.org/publicdomain/zero/1.0
    

    おめでとうございます

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

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

    個人的成長のためのロードマップ

    A developer needs to have specific skills/experience in order to be able to work on LibreOffice Code. This is the path suggested for anyone who wants to get involved in LibreOffice development:

    1. Understand intermediate level C++: Most of the LibreOffice code is in C++, so one should be fluent with C++ in order to be able to work with the code.
    2. Understand git and gerrit: git is the version control software that is used in LibreOffice. One should understand git and gerrit in order to be able to contribute
    3. Be able to build LibreOffice: To be able to change the code, one should be able to build LibreOffice from the sources.
    4. Do at least 10 bug triages: Developers should understand Bugzilla and the workflow associated with bugs and features. This is essential in order to be able to proceed.
    5. Do at least 5 EasyHacks with difficulty beginner (C++): The first step towards being able to understand and change the code.
    6. Do at least 5 EasyHacks with difficulty medium (C++): After doing some easier tasks, it is important to be able to do some more serious work.
    7. Do at least 1 EasyHacks with difficulty interesting
    8. Fix at least 5 regressions: Regressions are usually easy to reproduce, and can be fixed in a reasonable amount of time, so they are suitable for the newcomers
    9. Reach certain number of commits (~60)
    10. Do at least 1 CoreHack


    初心者のエチケット

    Experienced contributors will help you find solutions to your problems, but there are expectations and limits. Remote mentoring and troubleshooting has a greater cognitive load compared to being physically present. Showing you are well-prepared makes people more motivated to help you.

    General guidelines:

    • When using the chat, immediately describe your problem and stay in the channel for at least an hour.
    • For sharing text with multiple lines in the chat, use a paste service such as the one mentioned in the channel topic.
    • If you have network connection issues, the mailing list works better than the chat.
    • If you are doing a complex multi-step task, it is a good idea to keep personal notes. These will come in handy when you are asked what you did so far.
    • After receiving a reply, acknowledge it somehow. If you disappear without a trace, your helpers will feel distressed.

    If you are facing an issue with git, patch submission or setting up the development environment, it is best to follow these steps:

    1. Try to search for the how-to or solution yourself. Sometimes your helpers have to search as well.
    2. If your search was successful, make an attempt to follow the instructions.
    3. If you did not find any instructions or got stuck applying them, ask for help.

    With these types of issues, helpers are quite happy to try and solve your entire problem for you.

    If you are solving an easy hack, it is good to keep these facts and tips in mind:

    • There is no single document explaining the code base in prose. Educational material is scattered across conference presentation slides, blog posts and wiki pages.
    • The frequency of code comments is less than ideal (you can help!), so you should be prepared to read code.
    • Use git grep, an IDE and OpenGrok to find the definitions of the functions and classes you run into.
    • Investigate the commit history, also for similar topics elsewhere in the code base. OpenGrok's Annotate command can be revealing for this type of detective work.
    • Run a debugger while using LibreOffice to find out what is going on under the hood.
    • Browse the readme files.

    If you ask someone to say how to implement something, you will probably be faced with silence. Easy hacks are supposed to be a learning experience and mentors do not want to ruin it. A proposed implementation will be commented on in the review system.