mroongaからMroongaへ - ドキュメントの表記を一緒に更新しませんか?
リリースアナウンスや、公式ドキュメントをみてもうすでに気づいた人がいるかもしれませんが、Groonga関連のソフトウェアの表記を先頭が大文字へ統一する作業をすすめています。これにともない「mroonga」も「Mroonga」と表記するようにしはじめています。
ファイルはそれほど多くはないのですが、ドキュメントに散らばっている「mroonga」表記の統一をお手伝いしてくれる人を募集します。 詳細は後述する「協力者募集」を参照してください。コードを書かなくてもできることです。これを機会にMroongaのドキュメントに貢献してみませんか？
表記の統一について
これまでは、日本語の文の中や英語の文の途中では「mroonga」（先頭も小文字）という表記で、英語の文の先頭では「Mroonga」（先頭が大文字）という表記を使ったりしていました。これからは、日本語のときでも「Mroonga」（先頭が大文字）を使うようにします。
表記の統一の理由について
先頭を大文字に統一する理由は世界中で広く使われるようにしたいからです。
- 英語での表記 - テキストで大文字始まりだと固有名詞として認識してもらいやすい
- 日本語での表記 - 英語との統一性を重視して大文字に揃える
海外の人と英語でやりとりをすると、こちらは「mroonga」（先頭小文字）で書いても「Mroonga」（先頭大文字）で返ってくることが何度もありました。（あったと開発者である森さんから聞いています。）このことから、英語圏の人にとってはソフトウェアの名前は先頭大文字が普通なんだろうと感じるようになりました。Mroonga関連のソフトウェアは海外でも広く使われるようにしたいので、より海外でなじみやすい表記に統一することにしました。
ロゴへの影響について
ロゴについては見栄えを重視しているので「mroonga」（先頭も小文字）のままです。 したがってこれまで通り変更はありません。
次のように、テキストとロゴで表記が違う例というのはそれなりにあるためです。
協力者募集
具体的にどんなことをやればいいのかを説明します。基本的にはドキュメントのソースファイルごとにpull requestを送ってもらうと進めやすいです。
対象となるファイルはdoc/sourceディレクトリ以下の拡張子が「.rst」となっているファイルです。
あまりGitHubでの作業に慣れていなくてもできるように、「最初にやること」と「作業ごとにやること」、「ファイルごとにやること」に分けて順に説明します。
- 最初にやること
- 作業ごとにやること
- ファイルごとにやること
最初にやること
以下では、最初に一度だけ実施しておけば良いことを説明します。
最初の設定
まずは、gitの設定をしましょう。すでにある程度gitを使っている場合には初期設定はすでに完了しているかも知れません。その場合には飛ばして構いません。
% git config --global user.name "あなたのユーザー名"
% git config --global user.email "あなたのメールアドレス"
上記はコミットログに使われます。公開しても差し支えないユーザ名もしくはメールアドレスを設定します。
GitHubでforkする
GitHubにアカウントがなければ用意してください。アカウントが用意できたら、ログインした状態で以下のURLにアクセスします。
リポジトリ選択画面でご自分のリポジトリへとforkしてください。
作業用リポジトリの初期設定
次は作業用にforkしたリポジトリを手元にcloneします。このとき、本家の変更に追従するための設定を行います。
% git clone git@github.com:(あなたのGitHubのアカウント)/mroonga.git
% cd mroonga
% git remote add upstream git@github.com:mroonga/mroonga
ドキュメントビルド用の初期設定
ドキュメントを生成するために以下を実行します。
% ./autogen.sh
% ./configure --enable-document --with-mysql-source=(MySQLのソースディレクトリ)
ここまでで、「最初にやること」は完了です。次は「作業ごとにやること」へと進みます。
作業ごとにやること
以下では作業ごとにやることを説明します。
Mroonga本家に追従する
Mroonga本家の最新状態に追従して、作業がかぶらないようにします。
% git fetch --all
% git checkout master
% git rebase upstream/master
最新の状態に追従できたら、「ファイルごとにやること」へと進みます。
ファイルごとにやること
以下では、例えば http://mroonga.org/docs/characteristic.html を更新する場合で説明します。作業対象となるファイルは、リポジトリのdoc/source/ディレクトリ以下にあり拡張子が.rstなファイルです。今回は、doc/source/characteristic.rstを変更する例で説明します。
もうすでに統一作業が完了しているファイルについてはファイルの先頭に次のマークアップがしてあります。 実際の作業をするときには、まだそのマークアップがされていないファイルを選んでください。
.. -*- rst -*-
.. Mroonga Project
作業用のブランチを作成
作業対象のブランチを作成します。characteristic.rstを変更するので、
ブランチ名を use-capitalized-notation-characteristic とします。
% git checkout -b use-capitalized-notation-characteristic
編集作業
ドキュメントの「mroonga」という表記を「Mroonga」へと変更します。
文章だけでなく実行例も含むので単純に一括で置換するのは問題があります。 そこで「変更する箇所」と「変更しない箇所」について説明します。
変更する箇所:
- mroongaという単語をMroongaに置き換える
変更しない箇所:
- mroongaをURLの一部として使っている箇所
- mroongaをパッケージ名として使っている箇所
- ヘッダーファイルやソースコードのファイル名としてmroongaを使っている箇所
- mroongaを実行例として使っている箇所
- 行末が::で終わっている箇所の次のブロックは実行例となります。
例:
Here is an example how to check it::
mysql> SHOW STATUS LIKE 'Mroonga_count_skip';
+--------------------+-------+
| Variable_name | Value |
+--------------------+-------+
| Mroonga_count_skip | 0 |
+--------------------+-------+
1 row in set (0.00 sec)
ドキュメントの確認
マークアップに問題がないか、HTMLを確認します。HTMLを生成するには以下のコマンドを実行します。
% cd doc/locale/en
% make html
いつも使っているブラウザで該当ファイルを確認して、変更した内容が反映されていればOKです。
% firefox html/characteristic.html
コミット
HTMLに問題がないことを確認できたら、コミットします。
% cd ${cloneしたディレクトリーのトップディレクトリー}
% git add doc/source/characteristic.rst
% git commit
コミットするときのメッセージについては、例えば以下のようにします。
doc: use "Mroonga" notation
pushとpull request
ご自分のリポジトリにpushして変更点をとりこめるように公開します。
% git push -u origin use-capitalized-notation-characteristic
ここで use-capitalized-notation-characteristic
は前の方の作業で作ったブランチ名です。
ブラウザで https://github.com/(GitHubのアカウント)/mroonga を開くと「
use-capitalized-notation-characteristic 」ブランチをpull
requestする！みたいなUIができているので、そこのボタンを押してpull
requestしてください。入力フォームがでてきますが、コミットしたときメッセージで十分なのでそのままpull
requestしてOKです！
これで、ひととおりの作業は完了しました。
まだまだできるよ!という人は 「作業ごとにやること」の「Mroonga本家に追従」に戻って繰り返します。
