RAKUS Developers Blog | ラクス エンジニアブログ

株式会社ラクスのITエンジニアによる技術ブログです。

OSSコントリビュートの第一歩 - ドキュメント修正 -

f:id:tech-rakus:20210910150350p:plain

こんにちは、takaramです。

突然ですが、OSSへコントリビュートした経験はありますか?
今回は主に、OSSオープンソースソフトウェア)へのコントリビュートに興味はあるけどまだしたことがない、という人へ向けて、まず第一歩を踏み出してみよう!というお話をしたいと思います。

OSSオープンソースソフトウェア)について

オープンソースソフトウェアとは?

ソフトウェアのうち、ソースコードが一般に公開されていなかったり、利用が有償であるものを「プロプライエタリソフトウェア」と呼びます。有名なところではWindowsmacOSOracle database、Adobe Photoshopなどもプロプライエタリソフトウェアです。

それらに対し、利用者がソースコードの入手、利用、修正、再配布等を自由に行えるソフトウェアを「オープンソースソフトウェア (Open Source Software)」と言い、一般的に頭文字を取ってOSSと呼びます。単にソースコードが公開されているだけでなく、その改変なども自由に行えるところが特徴です。PHPRubyなどのプログラミング言語の処理系、MySQLPostgreSQLなどのDBMSFirefoxのようなWebブラウザOSSオープンソースソフトウェア)です。

厳密には、オープンソースイニシアティブという団体によってオープンソースの定義が決められており、これら10の条件に当てはまるものがOSSオープンソースソフトウェア)ということになります。

The Open Source Definition | Open Source Initiative

逆に言えば、この定義に沿うように公開すれば先述したような大規模なものでなくとも、一個人が開発したものでもOSSオープンソースソフトウェア)にすることができます。

オープンソースソフトウェアのメリット

OSSオープンソースソフトウェア)を利用するメリットとしては、以下のようなものがあると言われています。

  • 基本的に無償のためコストを抑えられる
  • 問題があっても自分で修正できる
  • 提供元の倒産、買収で突然使えなくなる心配がない

今や様々な種類のソフトウェアがオープンソースになっており、OSSオープンソースソフトウェア)を使ったことのないエンジニアはいないと言っても過言ではないほどに普及しています。

OSSコントリビュート

OSSの開発に関わることをOSS活動といいます。自分で開発したソフトウェアを公開することもそうですし、既存のOSSにバグ報告や機能追加の提案、修正パッチを送ることで貢献(コントリビュート)することもOSS活動になります。

自分が利用しているOSSに対してコントリビュートすれば、そのまま自分たちの利益になるのはもちろんですが、その他にもOSS活動を行うことで、

  • 自分の技術力の向上につながる
  • 就職・転職の際に評価してもらえる

などのメリットがあります。そのため最近では自社のエンジニアに対しOSS活動を推奨するIT企業も増えてきています。(弊社ラクスの開発部でも、社員の自己研鑽の一環としてOSS活動が推奨されています!)

とはいえ、「なんだか難しそう」と漠然とハードルの高さを感じている人も多いのではないでしょうか。確かにいきなりバグ修正などに挑むのは少し難易度が高いかもしれません。
そこで、OSS活動の第一歩としてドキュメント修正から始めてみることをオススメしたいと思います。

ドキュメントの修正

仕事・趣味を問わず、コーディングを行う際は利用するプログラミング言語やライブラリの公式ドキュメントを参照することが多いのではないでしょうか? OSSの場合、そのドキュメントもまたオープンソースとしてメンテナンスされている場合が多いです。小、中規模のOSSであればソースコードとドキュメントが同じリポジトリにあることが多いですが、大規模なライブラリやプログラミング言語であれば、ドキュメントが別リポジトリになっているパターンもよくあります。

ドキュメントも当然人が作っているものですので、間違いや抜けがあることもあります。普段からドキュメントを読んでいる中で、そうしたミスや改善点を見つけることができれば、それがOSSドキュメントへのコントリビュートチャンスです! コードの修正に比べれば難易度、心理的なハードルとも幾分か低いのではないでしょうか。それでもそのOSSの利用者にとっては役に立つ、立派なコントリビュートと言えるはずです。

ここからは、筆者が実際にOSSのドキュメントを修正しプルリクエストを送った実際の事例を紹介したいと思います。

ケース1:誤記修正

筆者は普段の仕事ではPHPを使っているのですが、PHPのマニュアルは英語版を元として日本語を含む複数の言語に翻訳されています。ある時日本語版マニュアルを読んでいると、誤った説明になっている箇所があることに気が付きました。英語版を確認してみると正しい記述になっていて、翻訳時のミスのようだったので、修正のプルリクエストを送ってみることにしました。

PHP日本語版マニュアルは PHP: PHP マニュアル - Manual にありますが、これはDocBookというXMLの一種で書かれた文書をHTMLに変換したもので、DocBookファイル自体はGitHubで管理されています。修正するためにはまずそのリポジトリを探さなければいけないわけですが、たいていの場合ドキュメントのどこかにリポジトリへのリンクが存在します PHPの場合、ページの右上のSubmit a Pull Requestというリンクをクリックすると、該当のファイルをGitHubで閲覧することができます。

日本語版ならphp/doc-jaリポジトリの該当ファイルが開きます。

f:id:takaram:20210909021610p:plain
PHPマニュアルの"Submit a Pull Requst"リンク

バグ修正などであれば、ここでリポジトリをforkしてローカルにcloneして……などを行うのですが*1、今回は一文程度の修正なので、GitHub上で修正してしまうことにしました。 詳しいやり方はGitHubの公式ドキュメントに載っているためそちらをご確認いただければと思いますが、Webブラウザ上で手軽に修正からプルリクエストの送信まで済ませてしまうことができます。

なお、リポジトリによってはプルリクエストを送る際の作法や注意点を記載している場合があります。 PHP日本語版マニュアルの場合はREADME.mdに記載がありましたが、他のプロジェクトだとCONTRIBUTING.mdのような名前のファイルに書かれていたり、GitHubWikiに記載されていたりというパターンもあります。 プルリクエストを送る前には一度確認しておいて方がいいでしょう。

さて、プルリクエストの送信まで完了すれば、あとはリポジトリへのコミット権限を持つメンテナが修正内容を確認してくれるのを待ちます。どのくらいで確認してもらえるかは一概には言えませんが、今回送ったプルリクエストは半日程度で見ていただき、そのまま問題なくマージされました。

github.com

このような大規模OSSの日本語版ドキュメントの場合、リポジトリの管理者も基本的に日本語が通じるので、プルリクエスト等でのやり取りも日本語で行えます。 英語に苦手意識がある人でも問題ありません。

ケース2:ドキュメントページの表示改善

こちらはRubyの日本語版リファレンスにプルリクエストを送った事例です。 Rubyは日本生まれの言語ということもあってか、日本語の公式リファレンスが英語版とは独立して存在しています。

docs.ruby-lang.org

このリファレンスを参照している際に、一部のページで若干表示が崩れる箇所があるのを発見しました。よくよく見たところ、Chromeでは発生せず、IEFirefoxでのみ起こるようでしたが、HTMLとCSSをいじれば対応できそうだということがわかったため、プルリクエストを送ることにしました。

RubyのリファレンスもPHPと同様、別形式(Rubyリファレンスの場合はRD形式)で書かれたファイルをプログラムでHTMLに変換しています。今回はHTMLを修正する必要があったため、この変換プログラム側に手を加える必要がありました。調べたところ、このプログラムはドキュメント (rurema/doctree) とは別のリポジトリ (rurema/bitclust)になっているようです*2

今回はGitHubでブラウザ上で修正、とはいかなかったので、ローカルにcloneしてきて修正を行いました。初めて見るリポジトリで多数のファイルがありましたが、今回は出力されるHTMLとCSSさえ変更できればよかったので、全部を把握する必要はないと判断し、それっぽい箇所を検索で探し当てながら修正を行いました。

そうして修正を終え、手元で実際に試して問題ないことを確認してプルリクエストを作成しました。

github.com

すると3日後にコメントが付き、少し違った修正方法の提案を頂くことができました。確かにそちらの修正のほうが良さそうだと考えたため、コミットの修正を行いました*3。その後少し時間は空きましたが、無事にマージされました!

この事例ではプログラムの修正を行っているので、1つ目の誤記修正に比べればハードルが高そうにも思えますが、万が一自分の修正に問題があった場合でも言語やライブラリ本体の修正ほどは影響が大きくないはずです。そう考えれば少し手を出しやすいのではないでしょうか?

最後に

OSSへのコントリビュートの第一歩として、まずドキュメントの修正から入ることのメリットをお伝えしました。普段使っている言語やライブラリのマニュアルに間違いや誤字脱字を見つけたら、「そのうち誰かが直すだろう」ではなく自分で修正してみるのはいかがでしょう? そうしてOSSにプルリクエストを送ることに慣れてくれば、次のステップとしてソースコードの機能追加やバグ修正にも踏み出しやすくなることと思います。

ちなみに、先日弊社で開催したOSS LT会 vol.2でも同じテーマでお話ししましたので、よければこちらのスライドも合わせてご覧ください。 www.docswell.com


  • エンジニア中途採用サイト
    ラクスでは、エンジニア・デザイナーの中途採用を積極的に行っております!
    ご興味ありましたら是非ご確認をお願いします。
    20210916153018
    https://career-recruit.rakus.co.jp/career_engineer/

  • カジュアル面談お申込みフォーム
    どの職種に応募すれば良いかわからないという方は、カジュアル面談も随時行っております。
    以下フォームよりお申込みください。
    forms.gle

  • イベント情報
    会社の雰囲気を知りたい方は、毎週開催しているイベントにご参加ください! rakus.connpass.com

*1:もっとも最近はGitHub Codespacesを利用すれば、ローカルへのcloneは必須ではないかもしれませんが

*2:PHPマニュアルの場合もやはりHTMLへの変換プログラムは別リポジトリになっています

*3:個人的な印象ですが、OSSではコミット履歴をきれいにするためこうしたレビュー後の修正は別コミットにせず1コミットにまとめてforce pushすることが多い気がします

Copyright © RAKUS Co., Ltd. All rights reserved.