GitHub

Contributing

このページでは、このパッケージに貢献する際に従うべきいくつかのガイドラインについて説明します。

Branches

Documenter バージョン 0.3 以降、release-* ブランチはこのパッケージのタグ付きマイナーバージョンに使用されます。これは、メインの Julia リポジトリで使用されているのと同じアプローチに従っていますが、はるかに控えめな規模で行われています。

可能な限り、release-* ブランチではなく master ブランチに対してプルリクエストを作成してください。

Backports

バグ修正は、JuliaDocsのメンバーによって git cherry-pick -x を使用して release-* ブランチにバックポートされ、その特定のマイナーバージョンのパッケージのポイントリリースで利用可能になります。

コミットをバックポートする必要があると思われるものがあれば、問題を開いて自由にノミネートしてください。METADATA.jlに新しいポイントリリースをタグ付けするリクエストも同様に行うことができます。

release-* branches

  • 各新しいマイナーバージョン x.y.0 には release-x.y というブランチが作成されます (a protected branch).
  • 新しいバージョンは通常、release-x.y ブランチからのみタグ付けされます。
  • パッチリリースの場合、変更は標準名「Backports for x.y.z」とラベル "Type: Backport" を持つ単一のPRを介して release-x.y ブランチにバックポートされます。PRメッセージはバックポートにコミットを提供しているすべてのPRへのリンクを含んでいます。PRはマージコミットとしてマージされます（すなわち、スクワッシュされません）。
  • 古い release-* ブランチは、その有用性が失われた後に削除される可能性があります。
  • パッチバージョン milestones は、どのPRがバックポートされるかなどを追跡するために使用されます。

Style Guide

周囲のテキストのスタイルに従って変更を行ってください。新しい機能を追加する際は、可能な限り以下のポイントに従ってください。

Julia

DocumenterはコードフォーマットにRunic.jlを使用します。さらに、以下のスタイルガイドラインに従う必要があります：

  • function ... end を使用するのは、メソッド定義に複数のトップレベル式が含まれている場合です;
  • 関連する短形式メソッド定義の間に新しい行は必要ありません;
  • 無関係または長い形式のメソッド定義は、それぞれの間に空行を挿入する必要があります;
  • module ... end を含むファイルは、モジュールの名前にちなんで名付ける必要があります。
  • メソッドの引数は、メソッド本体内での使用頻度に基づいて順序付けるべきです;
  • 他のモジュールから拡張されたメソッドは、上記のルールではなく、継承された引数の順序に従わなければなりません;
  • 可能な限り密な表現を避ける。例えば、複雑なネストされた ? よりもネストされた if を好む。
  • マルチラインコメント（#= と =#）を使用しないでください。
  • 長い行は可能な限り92文字に近く折り返してください。これにはドキュメンテーション文字列も含まれます。
  • Baseで使用される標準の命名規則に従ってください。

Markdown

  • 不均衡な # ヘッダーを使用します。つまり、ヘッダー テキストの右側に # はありません。
  • toplevelブロックの間に1つの空白行を含めてください;
  • 順不同リストは、2つの前置スペースを持つ * バレットを使用しなければなりません;
  • 了解しました。行を強制的に折り返すことはしません。
  • 強調（*）と太字（**）は控えめに使用してください;
  • 常にインデントされたブロックの代わりにフェンシングコードブロックを使用してください;
  • Juliaのドキュメントページに記載されている規約に従ってください。

Changelog

すべてのプルリクエストでユーザーに見える変更を行うものは、Keep a Changelog スタイルに従ってフォーマットされたチェンジログエントリを持っている必要があります。

Tests

Unit tests

Juliaパッケージの慣例に従い、ユニットテストはtest/*.jlにあり、エントリーポイントはtest/runtests.jlです。

End to end testing

テストは、ソースから例のパッケージドキュメントをビルドし、結果を検査する（エンドツーエンドテスト）ために /test/examples にあります。主なエントリーポイントは、ビルド用の test/examples/make.jl と、生成された出力に対して基本的なチェックを行うための test/examples/test.jl です。