Julia - 野良パッケージを公式パッケージにする方法

先日、DiracNotation.jl という拙作が METADATA.jl にマージされ、野良パッケージから公式パッケージ*1へと昇格しました。 Julia 1.0 が出て以降では初めてパッケージを新規登録したので不安もあったのですが、とりあえず無事にマージされてほっとしています。

github.com

最近、METADATA.jl を覗いていると新規のパッケージ登録も多く見られるので、自分のパッケージも公式パッケージにしたくてウズウズしている Japanese Julian*2 もきっと多いことでしょう。

しかし、Julia 1.0 になって公式ドキュメントから公式パッケージへの登録方法が消え、またパッケージの管理方法も変わったので、どうしたら公式パッケージとして登録できるのか分からず困っている Julian も多いのではないでしょうか。

そこで今回は野良パッケージを公式パッケージに登録するまでの方法を紹介します。

(注) Julia 1.0 がリリースされてから1ヶ月以上経ちましたが、既存のパッケージの Julia 1.0 への対応だったり、Bug fix に追われているせいか、パッケージの作り方・登録の仕方に関しては後回しになって曖昧な状態になっていると感じます。 パッケージのテンプレートを作ってくれる PkgDev.jl もまだ Julia 1.0 に対応していませんし。
そのため、ここで書いたことが1週間後、1ヶ月後にも通用する保証はありません。

目次

環境

  • Julia 1.0

対象

本記事は以下の項目全てを満たす方を対象としています。

  • METADATA に登録をしたことがない Julian
  • Julia 1.0 向けのパッケージを作る Julian
  • Linux or Mac でも動くパッケージを作る Julian *3

必要なもの

  • 英語で質問された時に下手でも良いから伝えようとする気持ち
  • 自分のパッケージを公式パッケージにしても良いだろうという根拠のない自信
  • METADATA.jl に PR を投げる勇気

野良パッケージ作り

野良パッケージを作っていない人は、まずは野良パッケージを作ってください。大雑把な作り方に関しては過去の記事をご覧ください。

goropikari.hatenablog.com

基本的なパッケージ構成

以降では今回私が作った DiracNotation.jl を元に具体的に説明していきます。

パッケージの最小構成は以下のようになっています。

DiracNotation.jl/
├── .git
├── .gitignore
├── LICENSE.md
├── README.md
├── REQUIRE
├── src
│   └── DiracNotation.jl
├── test
│   └── runtests.jl
└── .travis.yml

Julia 1.0 が出る前に PkgDev.jl を使ってパッケージを作ったことがある人ならお気付きかもしれませんが、Julia 0.6 時代の構成と変わりません。

野良パッケージの時は必要なかった REQUIRE は必須で、野良パッケージの時に必須の Project.toml はなくても構いません。
(むしろ Project を JuliaCIBot は扱えないから入れないでと私より前に PR を投げていた人は言われていました*4。そんなこととは露知らず私は Project 込みで PR 投げましたが JuliaCIBot のテストも通ったし、特に何か指示されることもありませんでした。 なので結局 Project を入れて良いのか、入れないほうが良いのかよくわかりません。)

以前紹介したパッケージの作り方 に則ってパッケージを作った場合、LICENSE.md, README.md, REQUIRE, .travis.ymlが足りないので追加します。

LICENSE

ライセンスは適宜決めてください。Julia のパッケージの場合 MIT LICENSE を採用しているものが多いです。特にこだわりがない場合は MIT LICENSE にしておけば良いと思います。

ライセンスファイルは Github
Create new file --> ファイル名に LICENSE と打つと Choose a license template と出るのでクリック --> ライセンスを選ぶ
とすると簡単に作れます。

f:id:goropikarikun:20180920011848p:plain

f:id:goropikarikun:20180920011855p:plain

f:id:goropikarikun:20180920011902p:plain

README

作ったパッケージがどんなパッケージなのか README に軽く書きましょう。

Julia では、公式パッケージに登録する場合レビューが入るので README にどんなパッケージなのかの説明がないとレビュアーが困ってしまいます。

README に使い方を書くか、別枠で使い方のドキュメントをちゃんと作りましょう。 「ドキュメントがないと悲しくなる」と Udacity の人も言っていたので、ドキュメント大事。 www.udacity.com

Travis CI

f:id:goropikarikun:20180920014226p:plain

Julia の公式パッケージに登録する場合は JuliaCIBot *5 のテストは通せなくても Travis を通すのは必須です。 Travis でのテストが失敗すると「テスト失敗してるよ」とツッコミが入ります。

.travis.yml は外部ライブラリ*6に依存していない限り、大体こんな感じに書いておけば良いと思います。

language: julia
os:
  - linux
  - osx
julia:
  - 0.7
  - 1.0
  - nightly
matrix:
  allow_failures:
    - julia: nightly
notifications:
  email: false

テストできる OS は Linux または Mac です。必ずどちらかは入れてください。ここで Windows は使えません。

Julia の項目はパッケージが対応している Julia のバージョンを明示的に書いてください。release と書くと「明示的に書いて」とレビュアーから言われます。

REQUIRE

現状で一番面倒くさいことになっているのが REQUIRE です。Julia 1.0 向けのパッケージなのに Julia 0.x の作法に則らなければなりません。

野良パッケージ作成時に作った Project.toml のようなものなんですが少し違います。 以前の記事では例え標準ライブラリだろうとも Project.toml に書かなければならないと書きましたが、REQUIRE では逆に標準ライブラリを書いてはいけません。

依存している外部パッケージのみ REQUIRE自力で書いてください。Project.tomlと違って自動で作ってはくれません。 ここいう外部パッケージは公式パッケージに限られます。

今回私が作った DiracNotation.jlREQUIRE はこんな感じです。

julia 0.7
Requires

julia 0.7 と書くと Julia v0.7 以降の Julia を対象としているという意味になります。Julia 1.0 向けのパッケージだったら v0.7 を対応に入れなくても良いのですが、まだ Julia 1.0 に完全移行できていない人もいると思うので Julia 0.7 も対応に入れておくと良心的かなと思います。v0.7 = v1.0 + deprecation warning なので v0.7 を入れても問題ないはずですし。

外部パッケージの方にも適宜対応しているバージョンを書いてください。

私が初めて METADATA にパッケージを登録した時は「対応している外部パッケージのバージョンも書いて」と言われたのですが、最近はあまり言われていない印象です。レビュアーによってその辺のさじ加減は違うのかなという気はします。 ただ、メジャーバージョンが上がる前のパッケージでしか動かないなどという場合はちゃんと REQUIRE にバージョンも書きましょう。そうしないとそもそも travis で失敗すると思いますが。

対象とするバージョンの詳しい書き方は v0.6 時代のドキュメントを読んでください。

Packages · The Julia Language

パッケージの名前

公式パッケージにする場合、パッケージの名前にも注意を払う必要が有ります。

とりあえず、

  • 略語を入れない
  • パッケージ名に Julia という単語を入れない
  • アッパーキャメルケースにする (私のパッケージの場合、Diracnotation でなく DiracNotation にする)

ということを守っておけばパッケージ名に関しては何も言われないのではと思います*7

詳しいことは v0.6 時代のドキュメントを読んでください。

Packages · The Julia Language

METADATA に PR を投げる

全ての準備は整いました。あとは PR を投げるだけです。 自力で PR を投げる場合、METADATA.jl を fork して編集して・・・ とやるのですが、今は attobot という便利なツールがあるのでこれを使いましょう。むしろ自力で PR を投げると「次回からはattobot使ってね」と言われるので初めから attobot 使いましょう。 attobot を使うと Github 上でバージョンタグを付けると自動で METADATA へ PR を投げてくれます。

github.com

https://github.com/integration/attobot にアクセスすると、attobot をまだインストールしていない場合、Install 画面が出ると思うのでインストールしてください。

そのあと、Configure -> Select repositories -> METADATA に PR 投げたいパッケージを選ぶ -> Save

f:id:goropikarikun:20180920092203p:plain

f:id:goropikarikun:20180920092211p:plain

attobot を入れたら Github 上でバージョン番号でタグ付けします。バージョン番号はセマンティック バージョニング に従ってください。以前は初回リリース時は v0.0.1 と付けるのが普通でしたが、最近は v0.1.0 から始めるようです。

タグ付けすると自動的に METADATA.jl へ PR が投げられます。私のような OSS 開発素人は一番緊張するところです。

semver.org

f:id:goropikarikun:20180920093313p:plain

f:id:goropikarikun:20180920093322p:plain

f:id:goropikarikun:20180920093331p:plain

Publish release をクリックしたら自動的に METADATA.jl に PR が投げられます。こんな感じ。

f:id:goropikarikun:20180920093758p:plain

30秒経っても PR が作られない場合、「PR が作られないのだけれど。。。」と attobot のリポジトリに issue を立ててください。中の人が対応してくれます。

私は一度だけ PR が出来なかったことがあるのですが、その時は Travis が終了する前に PR を投げたのでそのせいなのかなぁと思いました。真相は結局わかっていませんが 。

あとは静かに3日待ちます。投げた PR に3日間コメントがないと自動的にその PR はマージされるらしいです*8 *9*10

あなたの PR よりも後に出した PR の方が先にマージされることがありますが文句を言ってはいけません。すでに公式パッケージになっているもののバージョン上げの場合、速攻マージされます。新参者は静かに待ちましょう。

特に問題がなければ以下のようにマージされます。☆-ヽ(*´∀`)八(´∀`*)ノイエーイ

f:id:goropikarikun:20180920095554p:plain

パッケージ名だけで追加できちゃう(σ・ω・)σYO♪
公式パッケージのみに許された特権だ (σ≧∀≦)σчоッ☆ f:id:goropikarikun:20180920104805p:plain

おわりに

いかがだったでしょうか?公式パッケージにするまでの方法の雰囲気はつかめましたでしょうか?

Julia の公式パッケージ作りは全て英語でやりとりしないといけないので、私のような英語が苦手な人にとってはなかなか大変ですが、苦労した分 公式パッケージとしてリリースできたときの達成感は何ものにも代え難いです。

私のような素人 Julian でも出来るのですから、皆さんも気楽に Let's try!!!

パッケージ作りでわからないことがあったら公式の Discourse か Slack で聞いてください。

Julia Community

余談

パッケージを作った当初は公式パッケージにするつもりはなかったのですが、QuantumOptics.jl の gitter にて JuliaDiffEq で有名な Rackauckas さんに私の野良パッケージへのリンクを貼っていただき、まわりの反応もそんなに悪くなさそうだったので公式パッケージにしてもいいかなぁという気になりました。

f:id:goropikarikun:20180920110430p:plain

また、前々から外部パッケージに依存しないパッケージを作りたいなぁと思っていたのと*11、パッケージを Julia 1.0 でも動くように直したら「公式パッケージにしたいなぁ」という謎の衝動に駆られたので公式パッケージとしてリリースすることにしました。

正直に言って pretty-print は自己満足の世界ですし、なくても困らないのでこのパッケージが使われることは殆どないと思いますが、パッケージのリリースアナウンスツイートが Julia 創始者の一人である Viral B. Shah さんからリツイート & いいね をもらえたのでそれだけで私は満足です。

*1:ここでは METADATA.jl に登録されているパッケージを公式パッケージ、登録されていないパッケージを野良パッケージと呼ぶこととします。

*2:Julian = Julia user

*3:Linux だけ、 または Mac だけで動くパッケージの場合はこの記事の内容で大丈夫ですが、Windowsだけで動くものを登録したい場合はこの記事の内容が通用しません。

*4:Register new package Catsay.jl v0.1.0 by attobot · Pull Request #17687 · JuliaLang/METADATA.jl · GitHub

*5:METADATA に PR 投げた時のみに走るテスト

*6:Juliaのパッケージでなく、C 言語のライブラリとかのこと

*7:代替案を出されることも有ります。

*8:Tag Reinforce.jl v0.1.0 by attobot · Pull Request #18098 · JuliaLang/METADATA.jl · GitHub

*9:Register new package DrawSimpleGraphs.jl v0.1.0 by attobot · Pull Request #18043 · JuliaLang/METADATA.jl · GitHub

*10:私は、この「3日で自動的にマージする」という規則を知らなかったので、「回りの人たちにはレスポンスがあるのに何故私のところには何もないの。。。自分でも謎のパッケージ作ったなという自覚はあるけど、コメントするのも憚られるほど!?」と不安になったのですが、コメントがあると自動マージ機能が無効になるというコメントを見て、「むしろ私のパッケージ優等生じゃん!」と開き直れました。

*11:依存があるとパッケージの読み込みが遅くなるし、メンテナンスが面倒