貢献のサブミット¶
NGINX の Wiki はSphinx Documentation Generatorを使って自動的にreStructuredText filesから生成されます。ソースファイルはGitHubにあり、プルリクエストを使った貢献に開かれています。このドキュメントはこのプロセスを案内するのに役立つでしょう。
GitHubの編集¶
wikiを見ている間、あらゆるページのサイドバーに"Edit on GitHub"を見つけるでしょう。Using this you can edit edit page content and submitting your edits will generate a pull request. これは素早く編集を行う比較的簡単な方法です。
ローカルコンピュータ上で編集する¶
これらの紹介はLinuxとMacユーザのためのもので、あなたがGitHubアカウントを持ち、git コマンドラインツールがインストールされていると仮定しています。
python-sphinxもインストールされている必要があります; 幾つかのLinuxディストリビューションはリポジトリ内にこれをもち、それ以外ではpipを使ってインストールすることができます:
$ pip install -U Sphinx recommonmark commonmark
GitHubの2つの要素の認証¶
GitHubの2つの要素の認証 (とてもお勧めします)を使う場合、GitHubにアクセスする時にこのドキュメントで概要が説明される指示を使ってパスワードの代わりにアクセストークンを使うことができます。これは アプリケーション設定ページから取得することができます。
別のやり方として、GitHubにアクセスするためにSSHを使うことができます。単に SSH keys pageにいき、キーを登録し、このドキュメント内のURLをhttps://github.com/<user>/nginx-wiki.git から git@github.com:<user>/nginx-wiki.git に変更します。
フォーク¶
作業領域ができるようにソースのforkを生成する必要があります。これをするためには、NGINX Wiki GitHub pageに行き、サインインし、トップ知覚のFork ボタンをクリックします。一旦フォークすると、取り掛かるためのこのフォークのローカルコピーを取得することができます。これをするには、コンソール内で以下のコマンドを実行します(user>はあなたのユーザ名です):
$ git clone https://github.com/<user>/nginx-wiki.git
そして、ローカルクローンをupstreamのリポジトリに関連付ける必要があります:
$ cd nginx-wiki
$ git remote add upstream https://github.com/nginxinc/nginx-wiki.git
ブランチ¶
Wikiにマージしたい追加/編集の全ての新しいバッチは、独自のブランチを必要とします。新しいブランチを作成する前に、まずローカルコピーが最新であることを確認します:
$ git checkout master
$ git pull --ff-only upstream master
$ git push
そして、マスターに基づいた新しいブランチを作成することができます(<branch-name> をブランチのために選択した名前に置き換えてください):
$ git checkout -b <branch-name>
テスト¶
編集のテストの準備ができたら、正しくビルドできたかを確認するためにこれらのコマンドを実行します:
$ make html
$ make linkcheck
注意
The rendered output used by the published wiki is using make dirhtml which is identical but has a wiki page per directory rather than per html file.
In addition the full output is rebuilt on every execution of make dirhtml rather than just the changes with make html.
If either command generates an error, your edits probably need fixing. NGINXコミュニティチームはこれを喜んで手助けするでしょう。
PHPのビルトインサーバを使って出力をプレビューするには:
$ cd build/html/
$ php -S localhost:8000
そして、http://localhost:8000/ に行くためにwebブラウザを使って、結果を見ることができます。
コミットとプッシュ¶
変更をコミットする準備ができると、クローンしたリポジトリ内でそれらをコミットしGitHubにそれらをプッシュする必要があります。
以前にGitHubにコードをプッシュしたことが無い場合は、gitを使って登録するためにこれらのコマンドを実行します:
$ git config --global user.name "Real Name"
$ git config --global user.email "me@me.com"
新しいファイルをリポジトリに登録するためにgit add を使用し、それからコミットします:
$ git commit -a
デフォルトのテキストエディタがポップアップします。コメントの上にコミットメッセージを入力します。最初(題名)行は50文字未満でコミットの目的を説明しなければなりません。2行目は空白でなければなりません。3行目以降は各行72文字未満で詳細を含めることができます。
コミットが問題を修正する場合は、最初の行はissue #45のためのこの例のようなものになるでしょう:
Fixes nginxinc/nginx-wiki#45
全てのコミットが完了すると、変更が正しくマスターブランチにマージされるようにクイックリベースをする必要があるかも知れません。
$ git fetch upstream
$ git rebase -i upstream/master
Your editor should pop up again with a commit-style message that has pick as the first word. メッセージを保存し、リベースが完了するでしょう。コンフリクトがあるとリベースが伝える場合、git diffを使って問題を探し出し、修正し、これらのコマンドを実行する必要があるでしょう:
$ git add <filename>
$ git rebase --continue
問題が起きているように見える場合は、以下のコマンドを使ってリベースを元に戻し、助けを求めるためにNGINXコミュニティに接触することができます:
$ git rebase --abort
これで、GitHubにプッシュする準備ができている筈です:
$ git push --set-upstream origin <branch-name>
プルリクエスト¶
GitHubのwebサイト上のリポジトリに行くと、プルリクエストを提出するための選択を見るでしょう。Use this to submit a pull request upstream for your branch. プルリクエストを提出する前にブランチに複数のコミットをすることを歓迎します。