CONTRIBUTING.md

貢献

ドキュメント生成に貢献して頂ける方を歓迎します。そこで、このリポジトリ内での作業を、できるだけやりやすくしたいと思っています。まずはじめに取り決めて頂きたいことは、どのブランチに基づいて作業を進めるかです。よく分からない場合は、聞いて頂ければお答えします。あなたが誤ったブランチに基づいて作業していることにレビューアーが気づいたら、リベースして頂くようにお伝えします。

メモ: Docker プロジェクトへコード提供をする場合は、貢献のためのガイドラインを参照してください。

編集対象外のファイル

.NOT_EDITED_HERE.yaml というファイルの path: キーに列記されているファイルやディレクトリは、他のリポジトリにおいて管理されているものです。そのためこのリポジトリ内では編集しないでください。そのようなファイルに対してプルリクエストをあげてもリジェクトされます。 その編集は、YAML ファイル内の source: キーに示されているレジストリやパスにおけるファイルに対して行ってください。

クィックスタート

ドキュメントを読んでいて何か問題を見つけ、それをご自身で直したいと思った場合は、各ページの下の方にある Edit this page リンクをクリックしてください。Github エディターのページが開きます。Git についてあるいはマークダウンについて、あまり知識がなくても進められます。

保存の際に、まだフォークしていなかったら、フォークを生成するかどうかを聞かれます。 フォークを生成すれば、そのフォーク内にブランチを生成します。 是非、試してみてください。

全体的なドキュメントの改善

コミットはたいていは master ブランチに対して行います。 このブランチでは以下を行います。

• 新機能には特定されない概念的あるいはタスクベースの情報
• 再構成、再記述
• 文章のバグフィックス
• タイポや文法エラー

このプロジェクトの慣わしとして、masterブランチは公開用の最新ドキュメントを取り扱います。したがって開発中の新機能に関してはここで文書化はされません。新機能の文書化がどのように行われるかは、各プロジェクトにおける特定の新機能を参照してください。新機能に関するブランチは定期的に master にマージされます。このためタイポやバグに関してはあまり気にしないでください。

グラフィックを作成するのはお好きですか？ 良質のグラフィックは優れたドキュメントを作り出すための重要な要素です。グラフィックに関する貢献も特に歓迎します。

各プロジェクトにおける特定の新機能

{: #specific-new-features-for-a-project }

このドキュメントには多くのプロジェクトが含まれていて、そのリリース時期は異なります。プルリクエストを行う対象が、その時点でまだリリースされていない機能に関するものである場合に限り、リクエスト対象はそのプロジェクトの vnextブランチとしてください。 このブランチはmasterからクローンにより生成されたものであり、（移行のタイミングで）そのプロジェクトのmasterブランチのドキュメントがインポートされています。こうすることでコミット履歴が保持されます。そのプロジェクトが正式リリースされる際には、vnext ブランチが master にマージされることになるので、貢献した作業が docs.docker.com のもとで公開されることになります。

vnext ブランチは以下のところに存在しています。

• vnext-engine: docker/dockerプロジェクトの次期機能に関するドキュメント

• vnext-compose: docker/composeプロジェクトの次期機能に関するドキュメント

• vnext-distribution: docker/distributionプロジェクトの次期機能に関するドキュメント

• vnext-opensource: docker/opensourceプロジェクトの次期機能に関するドキュメント

• vnext-swarm: docker/swarmプロジェクトの次期機能に関するドキュメント

• vnext-toolbox: docker/toolboxプロジェクトの次期機能に関するドキュメント

• vnext-kitematic: docker/kitematicプロジェクトの次期機能に関するドキュメント

プルリクエストでの共同作業

プルリクエストを行っている他の貢献者が特に設定をしていない限り、その貢献者に対してコミットをプルすることができます。コマンドラインから追加やリモートのフェッチ、ブランチからのチェックアウト、コメントの追加などを行います。もっと簡単に Github ウェブ画面からコミットすることもできます。これを行うにはFile画面に表示されたファイルに対応した鉛筆アイコンをクリックします。

プルリクエストが行っている重要なコミットに対して、小さな追加のコミットがいくつか加わっていることがあります。このようなコミットは通常は「squashマージ」が行われ、1 つのコミットとしてマージされます。これが不適当である場合には、マージの際に個別にコミットが行われる場合もあります。

プルリクエストのガイドライン

プルリクエストのレビューを迅速に行えるように、以下のガイドラインに従ってください。

• 一つのプルリクエストにて多数のファイルを対象として含めることは、できるだけやめてください。

• 編集対象にしていないのに、理由もなく空白や改行文字を変更することはやめてください。利用しているテキストエディターが、ファイル保存の際にファイル全体の書式を自動変更するような設定にはなっていないことを確認してください。

• 長期に運用しているmasterやvnextといったブランチにおけるプルリクエストには Netlify によるテストが実行されます。そしてプルリクエストの結果はステージングサイトにデプロイされます。その URL は、プルリクエストのConversation画面の下部に示されています。ステージングサイトを確認し問題がないかどうか、もし必要なら修正を行ってください。レビューアーもステージングサイトを確認してください。

レビュー方法に関して改善すべき方法があればお伝えください。

スタイルガイド

Docker ドキュメントの書き方に関して質問がある場合は、まずはスタイルガイドを確認してください。このスタイルガイドでは、文法、フォーマット、スタイル、言語、表現の様子などを示しています。このガイドに不明な点があれば、issue をあげてお知らせください。またはプルリクエストをあげていただければ、改善していきたいと思います。