NGINX の Wiki はSphinx Documentation Generatorを使って自動的にreStructuredText filesから生成されます。ソースファイルはGitHubにあり、プルリクエストを使った貢献に開かれています。このドキュメントはこのプロセスを案内するのに役立つでしょう。
wikiを見ている間、あらゆるページのサイドバーに"Edit on GitHub"を見つけるでしょう。これを使って、ページのコンテントを編集することができ、編集はプルリクエストを生成するでしょう。これは素早く編集を行う比較的簡単な方法です。
これらの紹介はLinuxとMacユーザのためのもので、あなたがGitHubアカウントを持ち、git
コマンドラインツールがインストールされていると仮定しています。
python-sphinxもインストールされている必要があります; 幾つかのLinuxディストリビューションはリポジトリ内にこれをもち、それ以外ではpip
を使ってインストールすることができます:
$ sudo pip install -r requirements.txt
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 dirhtml
$ make linkcheck
もしどちらかのコマンドがエラーを起こす場合、あなたの編集はおそらく修正が必要です。
最近make linkcheck
を実行し、多くの恒久的なリダイレクトが見つかった場合は、以下を実行することでそれら全てを自動的に置き換えることができます:
$ make linkfix
このスクリプトは怠け者のための単なるクイックハックなので、コミットする前にそれが構文的に何も破壊していないことを確認してください。
出力をプレビューする一つの方法がNGINXを使うことです。NGINXをインストールしていればビルドシステムはすでにNGINXをセットアップする準備ができています:
$ make serve
あるいは非標準のパス(例えば /opt/nginx/
)にNGINXがある場合は以下を使ってNGINXバイナリのパスを示すことができます:
$ NGINX_PATH=/opt/nginx/sbin make serve
そして、webブラウザを使って http://localhost:8080/
に行き結果を見ることができます。
終われば、CTRL-C がNGINXを終了するでしょう。
変更をコミットする準備ができると、クローンしたリポジトリ内でそれらをコミットし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
最初の単語としてpick を持つコミット形式のメッセージがあるエディタが再びポップアップするはずです。メッセージを保存し、リベースが完了するでしょう。コンフリクトがあるとリベースが伝える場合、git diff
を使って問題を探し出し、修正し、これらのコマンドを実行する必要があるでしょう:
$ git add <filename>
$ git rebase --continue
問題が起きているように見える場合は、以下のコマンドを使ってリベースを元に戻し、助けを求めるためにNGINXコミュニティに接触することができます:
$ git rebase --abort
これで、GitHubにプッシュする準備ができている筈です:
$ git push --set-upstream origin <branch-name>
GitHubのwebサイト上のリポジトリに行くと、プルリクエストを提出するための選択を見るでしょう。これを使ってあなたのブランチについてのpullリクエスト upstream をサブミットします。プルリクエストを提出する前にブランチに複数のコミットをすることを歓迎します。