この記事は以前書いた記事「MELPAにレシピを投稿するには」の内容を、本家の最新のアップデート1に併せて、別記事として翻訳したものです。
↓ ここから翻訳 (途中)
MELPAは「レシピ」によって構成され、レシピごとに一つの「パッケージ」を記述され、一つの専用リポジトリで管理されます。この文書ではMELPAに新しいパッケージの登録を提案するための方法を説明します。
MELPAのメンテナンスには三種類の役割の人々が貢献しています:
- MELPAメンテナ
- 新しいレシピと関連パッケージのレビューや、システムの維持の責任を担います
- レシピ作者
- 良いレシピを提案し、メンテナンスする責任があります
(例: パッケージに名称変更や非推奨化などの変更があった場合など) - パッケージ作者
- 品質のよいEmacs Lispパッケージを書く責任があります
可能ならパッケージ作者もレシピ作者の役割を果たすことをお勧めします。
レシピ作者とパッケージ作者がMELPAにレシピを提案するための準備のガイドラインについて説明します。パッケージを採用するプロセスを迅速化するため、可能な限りガイドラインに従ってください。ガイドラインは絶対ではなく、正当な理由があればケースバイケースで判断されます。
Pull Requestの前に知ってほしいこと
新規のレシピ提出は以下のガイドラインに従ってください。
- フィードバックを待つ
- レビュープロセスにおいてMELPAメンテナは、MELPAとEmacsパッケージシステムが動くか確認するためにあなたのパッケージを見ます。MELPAメンテナは、あなたのパッケージをMELPAに追加するための障害や、そうではないことについてコメントをするかもしれません。
- Pull Requestごとに一つのレシピ
- 追加するパッケージが複数ある場合は、それぞれにPull Requestを作成してください。パッケージ同士が非常に密接に関連していて一つのリポジトリに含まれる場合(それが良い方法ではないことは後述します)は、一つのPull Requestにまとめて作成することもできます。その際は1コミットごとに一つのレシピを追加してください。
- 合理的で革新的なパッケージ
- MELPAは「精査された」Emacs Lispパッケージのセットを提供しています。全てのLispファイルを網羅するためのリストではありません。MELPAメンテナは既存のパッケージが提供している機能をコピーしたパッケージを拒否します。できれば新しいパッケージを作るのではなく、既存のパッケージを改良してみてください。
- ソフトウェア構成管理(SCM)
- 上流のソースコードはGitやMercurialなど権威あるSCMソフトウェアのリポジトリで管理される必要があります。EmacsWikiのパッケージはもはや受理されません。
- 公式リポジトリ
- パッケージは公式のパッケージリポジトリから構築される必要があります。特別な事態を除いて、公式リポジトリからのフォークは受理されません。
- 専用のSCMリポジトリ
- パッケージはそれぞれ専用のSCMリポジトリ(Gitなど)で管理してください。MELPA StableはSCMのタグを参照してパッケージにバージョン番号を割り当てるため、パッケージごとに別々のバージョン番号を持つことができます。
- 品質
- 私たちはMELPAを構成する一部であるパッケージの品質に気を配っているので、MELPAメンテナはすべてのレシピと関連パッケージをレビューします。以下のガイドラインを読み、従ってください。
- パッケージ作成者への連絡
- あなたがパッケージの作者でもメンテナでもないなら、作者に連絡してPull Requestの過程に含めてください。
- レシピのメンテナンス
- パッケージ作者が上流リポジトリを移動したときは、レシピも更新してください。変更の前後がどちらもGitHubの場合は、パッケージ作者はGitHubのリポジトリ転送機能を使って移動するのがよいでしょう。そうした場合、MELPAメンテナが変更が妥当であることの確認が容易になります。それ以外の場合は、古いリポジトリのREADMEから新しいリポジトリにリンクする必要があります。
あなたのレシピをマージさせるための準備
MELPAメンテナは各レシピおよび関連パッケージの品質を管理しています。レビューのプロセスを遅れさせないよう、以下のガイドラインに従っておくことをお勧めします。
- コーディングスタイルと慣習
- Emacs LispファイルはEmacs Lisp conventions(規約)とEmacs Lisp Style Guideに従ってください。
- パッケージのメタデータ
- パッケージの説明は
(info "(elisp) Packaging")のドキュメンテーションで説明される通りのpackage.el形式に則る必要があります。この形式についての具体的な説明はmarmaladeパッケージのドキュメントをお読みください。 - 品質チェックツールを利用する
- Flycheckとpackage-lintおよびflycheck-packageは、あなたのパッケージから一般的なエラーを検出するのに役立ちます。また、checkdocによってパッケージがドキュメント文字列の一般的な規則に従っているかを確認できます。
- 長い関数を避ける
- 関数が長いほど何が起こるかの理解が難しくなり、MELPAメンテナが適切なフィードバックを与えることが困難になるおそれがあります。コード中の改善の余地があると特定の箇所を差して指摘することも難しくなります。長い関数は、より小さく、適切に名付けられ、よく文書化されたものになるよう工夫してください。
- (オプション)リリースのためにタグをつける
- あなたのパッケージの安定版を生成するには、
version-to-list関数と互換性のあるバージョン番号の形式でSCMリポジトリにタグをつけるだけです。そのタグがつけられたコミットは安定版パッケージとして生成されます。
典型的な問題を修正する
MELPAに提案されたパッケージには典型的な問題があり、その指摘によってレビューは数日から数週間遅れます。
パッケージの提出前にこのリストを再度確認してください。
- 上記で指定された品質チェックツールを実行してください (絶対に!)
-
それぞれのEmacs Lispファイルの最初の行に
-*- lexical-binding: t; -*-を付けることでレキシカルバインディングを有効化してください。なぜ常にそうしなければいけないかを知りたければChris WellonsのEmacs記事(特にSome Performance Advantages of Lexical Scope)を読んでください -
既存のFaceを
:inheritした上で属性を上書きする (例: 太字にする、下線をつける、色を反転させる) ような定義はやめてください。ユーザーの設定によっては、ひどいことになります。単に:inheritだけにして、ユーザー自身にカスタマイズさせるのがベストです。 -
コンパイラに関数参照を指示するために、関数名に単に
'をつける(つまりquote特殊形式)の代りに#'(つまりfunction特殊形式)をつけるようにします。(例:(seq-filter #'evenp list))
MELPAへのPull requestの準備
MELPAにPull requestを送るには、はじめにMELPAリポジトリをforksします。そして必要なレシピを追加し、テストしなければいけません。
レシピファイルの作成
package-build-recipes-dirで指定されたディレクトリ(デフォルトはpackage-buildがロードされた位置のrecipes/ディレクトリ)にファイルを作成します。package-build/package-build.elにあるpackage-build-create-recipeコマンドを使って工程を対話的に支援することもできます。ファイル名は、そのパッケージが提供する「feature名」と一致させる必要があります。
このファイルに記述する内容の形式はREADMEのrecipe format節を参照してください。パッケージ名はファイル名と一致しなければいけません。
レシピは関連するファイルのみを指定することで、生成されるパッケージのファイルサイズが最小になるようにすることが望ましいです。
レシピをテストする
以下の手順でパッケージが正しくビルドされるかどうかをテストできます。
コマンドラインからmake recipes/<name>を実行するか、レシピを編集中のバッファでC-c C-cを押すことでレシピをビルドします(以下、<NAME>は今回作成するパッケージ名=ファイル名を指します)。環境変数$PATHに含まれるemacsコマンドが23以上であるか、または環境変数$EMACS_COMMANDが適切なemacs実行ファイルのpathに設定されてることを確認してください。
リポジトリにリリースタグがつけられている場合はSTABLE=t make recipes/<NAME>を実行して、正しいバージョンが期待通りに特定されているかを確認してください。バージョン番号の記法は、レシピの:version-regexp節に記述することで変更することも可能です。詳細はREADMEのrecipe formatを参照してづあさい。
Test that the package installs properly by running package-install-file from within Emacs and specifying the newly built package in the directory specified by package-build-archive-dir (default: packages/ directory where package-build was loaded). Entering “yes” when prompted after pressing C-c C-c in the recipe buffer also works.
You can optionally run a sandboxed Emacs in which locally-built packages will be available for installation along with those already in MELPA:
EMACS_COMMAND=/path/to/emacs make sandbox INSTALL=
From within Emacs, install and test your package as appropriate. This is a useful way to discover missing dependencies.
Opening a pull request
Create a dedicated pull request branch in your clone of the MELPA repository and push this branch to your fork. Finally, go to the MELPA repository and open the pull request.
Include the following information in the pull request description:
a brief summary of what the package does;
a direct link to the package repository;
your association with the package (e.g., are you the maintainer? have you contributed? do you just like the package a lot?);
relevant communications with the upstream package maintainer (e.g., package.el compatibility changes that you have submitted).
Consider the hub command-line utility by defunkt which helps simplify this process.
Waiting for reviews and taking feedback into account
MELPA maintainers spend a lot of time reviewing proposed packages and also have quite a lot of other non-MELPA-related activities. Please be patient as it might take a week (sometimes several) before one starts having a look at your pull request.
If you were asked to make several changes, then you should explicitly mention everything that you have fixed, and possibly even link to the relevant commits. One way of doing that is to mention the MELPA pull request in every commit addressing one of the raised points: just write melpa/melpa#N in each commit message where N is the pull request number.
You can help MELPA maintainers take care of pull requests much faster by paying real attention to the quality of your package (see above for some quality checks and links). If you feel for it, you can also take another pull request and give feedback to the author.