Contrib How-To

Maven / Leiningen でライブラリを依存関係として含める方法

Jenkins と JIRA のライブラリページへのリンク

Maven Central と oss.sonatype.org で利用可能なリリースへのリンク

利用可能な場合は、生成された API ドキュメントへのリンク

一般的な使用方法 (どの名前空間を使用/require するかを記述する必要があります)

開発者向け情報：GitHub プロジェクト、バグトラッカー、継続的インテグレーション、互換性テストマトリックスへのリンク

すべてのリリースの変更履歴 (別のファイルでも可)

ライブラリをメンテナンスし、発生した質問/問題に対応する

master ブランチで作業するか、(一時的に分離しておきたい大きな塊を扱っている場合は)自分で作成した機能固有のブランチで作業する

GitHub の「オンデマンドリリース」アクションを使用してリリースを作成する

他のコミッターのライブラリを変更する前に、他のコミッターと調整する

CA に署名している場合にのみ、他の人からのコントリビューションを受け入れる

リリースブランチ (1.2.x のような名前) にプッシュしないでください

コントリビューターではない人のパッチを受け入れないでください

コントリビューターからのプルリクエストを受け入れないでください。パッチのみ受け付けます。

pom.xml のバージョン番号を変更しないでください。上記の Maven リリースプロセスを使用してください

CAをファイルに登録する

clojure-devメーリングリストに参加する

JIRA アカウントを作成する

Clojure コアチームに github ユーザー名と JIRA ユーザー名を知らせて、適切な権限を設定してもらう

Clojure コアチームは、build.clojure.org にアカウントを作成する必要もあります。以下を参照してください。

過去のコントリビューターはすべて、次のことを行う必要があります。

clojure-dev メーリングリストにメールを送信して、新しいプロジェクトの承認と GitHub、Jira、Jenkins の管理者権限を取得します。

clojure 組織の下に新しい GitHub リポジトリを要求する

新しい JIRA プロジェクトを作成する (JIRA 管理者権限が必要です)

ビルドの設定 (ステップ 2 を除き、Jenkins 管理者権限が必要です)

自動ドキュメント

リリースの実行

プロジェクトには -SNAPSHOT バージョンの pom.xml ファイルが必要です

pom.xml ファイルでは、build.poms の pom.contrib の最新リリースバージョンの親を指定する必要があります

プロジェクトには -SNAPSHOT バージョンの pom.xml ファイルが必要です

GitHub の "master" ブランチにプッシュする

Jenkins は GitHub をポーリングして自動的にビルドします

または、プロジェクトページで「今すぐビルド」をクリックすることもできます

Jenkins は、一意の番号が付けられた JAR ファイルをビルドし、Sonatype OSS スナップショットリポジトリにアップロードします

GitHub の "master" ブランチには、裸のバージョン番号ではなく、-SNAPSHOT バージョンの pom.xml ファイルが必要です

Jenkinsにログインします

プロジェクトのジョブに移動します

左側の「Maven リリースの実行」リンクをクリックします

「Maven リリースの実行」ページで

ビルドが正常に完了した後

ユーザーにバージョンを推奨している場合は、プロジェクトの README を更新することを忘れないでください。

major.minor.patch

可能な限り、破壊ではなく、追加と修正のガイドラインに従ってください

ルールは破られるためにあります。標準を把握しておいてください。ただし、絶対的なものとして扱わないでください。

名前と署名を正しく取得してください。Rich は既存のコードを壊さないという Java の取り組みを強く尊重します。実際には、実装を永久に調整できますが、名前と署名を公開したら、それを守る必要があります。（実際には、実装の詳細を確認していなくても、多くの人が名前と sig を確認する必要があると思います。）

クリティカルなコードに存在しそうな関数には型ヒントを使用します。それ以外の場合は、コードをシンプルにし、ヒントなしにしてください。

適切な名前を使用し、他の名前空間の名前と衝突することを恐れないでください。柔軟な名前空間サポートは、そのためにあります。

他のパッケージへの依存関係について、明確かつ最小限にするようにしてください。（:use よりも :require :refer を推奨します）

関数でジョブを実行できる場合は、マクロを使用しないでください。マクロが使いやすさのために重要な場合は、関数バージョンも公開してください。

コンパイル時にすべての情報があることが確実な場合は、パフォーマンスを重視するコードが向上するマクロを使用してください。

ライブラリレベルのドキュメント文字列を提供します。

自動化されたテストを提供します。

述語には「?」サフィックスを使用し、ブール値を返します。

コードで値が無視される構造化ターゲットと仮引数名には「_」を使用します。

ドキュメント文字列を含めます。

迷ったときは、パフォーマンスの高いバージョンを公開してください。Clojure は必要なときにパフォーマンスを有効にするために多大な労力を費やしており、lib も同様である必要があります。（たとえば、コアに multimethod + がないのはそのためです。）ユーザーは、必要に応じて、シンボルをハイジャックして、独自のより多態的な API を常に作成できます。

コアと衝突する適切な名前を使用する場合は、セマンティクスが並行になるようにしてください (場合によってはレイジーさを除く)。この良い例は、コアシーケンス関数をシャドウする文字列関数です。

assert と事前および事後条件を使用します。

可能な限り遅延評価にしてください。

pred や coll のような慣用的な名前については、clojure.core の例に従ってください。

clojure.core のプリアンブルコードの慣用句に従わないでください。Clojure はまだブートストラップされていないため、そのコードは制限された環境で実行されます。

要素を分解してください。もしあなたがRichでないなら、例えばdoseqの定義のように長いフォームを書かないでください。

オブジェクトのプロパティにアクセスするには、キーワードファーストの構文を使用してください：(:property object-like-map)

コレクションから値を抽出するには、コレクションファーストの構文を使用してください（またはコレクションがnilの可能性がある場合はgetを使用してください）：(collection-like-map key) または (get collection-like-map key)。すべてのコレクションがキーワードでキー付けされているわけではないことに注意してください。

イディオム的なコードでは、構造化束縛が多用されます。ただし、呼び出し側の契約の一部としてサブ構造を伝えたい場合にのみ、引数リストで構造化束縛を行う必要があります。そうでない場合は、最初の行のletで構造化束縛を行います。

設定よりも更新を優先してください。多くの理由があります：統一された更新モデルは、これを行うための簡単な標準的な方法を提供します。可換な操作を発見するのに役立ちます。更新しているオブジェクトについて想定している範囲を減らします。

間違ったコレクション型に対する操作をサポートしないでください。もしあなたのアルゴリズムがランダムアクセスでのみパフォーマンスを発揮する場合、ランダムアクセスを持つ引数を要求してください。

*earmuffs*は再束縛を意図したものにのみ使用してください。定数に特別な表記を使用しないでください。特に指定がない限り、すべてが定数とみなされます。

bang!はSTMトランザクションで安全でないものにのみ使用してください。

明示的なループ/recurよりもシーケンスライブラリの組み合わせを優先してください。

再束縛可能な変数は、スコープマクロ（例：inやwith-in-str）と組み合わせて使用する必要があります。

遅延シーケンスは、必要な最小限の状態のみを保持する関数として公開する必要があります。つまり、「頭を手放す」ようにします。呼び出し側が使用するローカルメモリの量を決定できるようにします。

Klass/staticField、(Klass/staticMethod)、(Klass.)および(.method obj)のインターオップスタイルを使用してください。唯一の例外はコード生成コードであり、古い(. obj method)スタイルの方が生成しやすい場合があります。

動的束縛（例：sqlのdb）を介して暗黙的にパラメータを渡すインターフェースを提供する場合、パラメータを明示的に渡す同じインターフェースも提供してください。

condのデフォルトケースを提供する場合、trueの代わりにキーワード:elseを条件として使用してください。

プライベート変数にアクセスするには（例：テスト用）、@#'some.ns/varという形式を使用してください。

プロトコル