MDN Web Docsへのコントリビュート手順(備忘録)
これはMDN Web Docsへのコントリビュートを実際に行った際の手順などをメモした備忘録となる。
目次
- 目次
- アカウントを作成(これは不要かもしれない)
- コントリビューションに関するMDNのドキュメント
- 英語以外のドキュメントにコントリビューションしたいとき
- 修正対象のファイルの探し方
- ローカルサーバで修正したドキュメント内容を確認する方法
- 実際にコントリビューションしてみた
アカウントを作成(これは不要かもしれない)
MDN Web Docsにアクセスすると、画面右上にあるSigninからアカウントを作成できる。
これが必須なのかはわからないが、とりあえずアカウントは作成してみた。
GitHub連携かGoogle連携か選べたので、GitHub連携で作成してみた。
ただ、その後の作業手順を考えると、別にコントリビュートをするのにアカウントは作らなくても良かったのではないかとも思ったりした。
(コントリビューション自体はGitHubアカウントがあればできそうだったので)
コントリビューションに関するMDNのドキュメント
コントリビューションに関するMDNのドキュメントは下記に記載されている。
まずはこちらを読んだ。
content/README.md at main · mdn/content · GitHub
MDNへコントリビューションする際はGitHubアカウントが必須
修正作業はGitHub経由で行われるのでアカウントを持っていない方はアカウントを作成するところから始める必要がある。
MDN の構成について
MDNのドキュメントとGitHubで格納されている実際のファイルの関係については下記に記載がある。
content/README.md at main · mdn/content · GitHub
英語以外のドキュメントにコントリビューションしたいとき
ちなみに上記リポジトリは英語のドキュメントのみを扱っている。
他の言語のドキュメントについてコントリビューションを行いたい場合は、下記のリポジトリを見る必要がある。
GitHub - mdn/translated-content: All translated MDN content in raw form
なお、現在は下記の言語しかコントリビューションを受け付けていないようだ。
これはアクティブなメンテナンスチームの言語のみを表しているとのこと。
- fr
- ja
- ko
- pt-BR
- ru
- zh (zh-CN and zh-TW)
修正対象のファイルの探し方
上の MDN の構成について でも書いたが、URLを見ながら実際に修正対象となるファイルを探していくことになる。
MDN Web Docsへコントリビューションする際に事前に知っておくべき情報は、これで以上となる。
ここからは実際にリポジトリで修正作業を行った際、修正内容をローカルで確認する方法について記載していく。
ローカルサーバで修正したドキュメント内容を確認する方法
1. まずは下記のリポジトリをどちらもcloneする
下記がMDN Web Docsの本体(英語のみ)
下記がMDN Web Docsの多言語に関するファイルが格納されている。
2. content repoのセットアップ
cloneした2つのリポジトリのうち、contentのルートで下記のコマンドを打って依存パッケージをインストールする
(ちなみに Node.jsのインストールと、 yarnのインストールは事前に済ませておくこと)
yarn install
3. 環境変数を追加
cloneしていたもう一つのリポジトリ translated-content のfiles のパスを CONTENT_TRANSLATED_ROOT にセットした状態で yarn startを行う
実際に打つ際のコマンドは下記。
CONTENT_TRANSLATED_ROOT=/path/to/translated-content/files yarn start
もしくは exportで環境変数を設定してからでも良い。
export CONTENT_TRANSLATED_ROOT=/path/to/translated-content/files yarn start
すると、ローカルサーバが立ち上がるので、 localhost:5000 にアクセスして確認が可能。
(アクセスした画面から指定のページに遷移し、 Change Language から指定の言語に変更できる)
環境変数追加の別の方法
上のやり方以外にも .env ファイルを用いて設定する方法もある。
こちらであれば以降はyarn startだけでOKとなる。
echo CONTENT_TRANSLATED_ROOT=/path/to/translated-content/files >> .env # .envに設定情報は記憶されるので、あとは "yarn start"でOK yarn start
ローカルでの確認方法については以上である。
実際にコントリビューションしてみた
今回修正しようと思ったファイルはこちらである。
日本語の誤字を見つけたので、その修正PRを作成することにした。
まずは上にも書いたtranslated-content のリポジトリを自身のGitHubアカウントにforkする
次は人によるかもしれないが、私はローカルに一度cloneしてから修正PRを作成、
上で書いたローカルサーバを立ち上げる方法で修正内容を確認したりしながら作業を実施。
実際に作成したPRが下記となる。
修正で凡ミスをしてしまっており恥ずかしい。
またPRを見てもらうと分かる通り、日本人の方に対応していただき、コミュニケーションは日本語で行うことができた。
(まだ一度PRを作っただけのため、毎回、日本語で行えるかどうかまでは分からない)
またPRのやり取りを見てもらうと分かる通り、実は日本語のドキュメントには修正必要な箇所や、不要なfontタグがソース内に散りばめられており(自動生成した際の痕跡とか？)、修正が必要な箇所は結構ありそうでした。
なお、日本語のドキュメントを修正する際は下記のガイドラインにも目を通しておくと良さそうだ。
というわけで、もしこの記事がMDNへコントリビューションしようか迷っている方の背中を押すきっかけになれば幸いです。
ちなみにMDNのPRを作成すると、最初に push した分の修正に対してPreview URLが発行されるので、そちらで一度修正内容を確認してみるのも良さそうです。
(自分はそこで確認するのも漏れていたので、これは自分に対する戒めでもあります。)
