blockdiag を github に移動しました。
blockdiag の開発拠点を bitbucket から github に移動しました。
開発を始めた 2011年ごろ、僕は git より mercurial を好んでいたので bitbucket をメインリポジトリとしてチョイスしたのですが、
CI などを含めた周辺サービスとして、github に破れた感が長引いていました。drone.io も止まっていましたしね。
長らく更新すらしていなかったので、完全に見て見ぬふりをしていたのですが、新たにバグが報告されたのを受けて
重い腰を上げて github に移行することにしました。
イシューの移動
ソースコードそのものは、github の import 機能がいい感じにやってくれるので、何も考える必要はありません。
しかし、イシューについてはそうもいきません。
そこで @shimizukawa さんが改造した bitbucket_issue_migrator を使います。
www.freia.jp
ただ、この記事にも書いてありますが、そのまま利用すると全ての移行イシューの投稿者が自分になってしまいます。
その例として、Sphinx では先頭 2000件ぐらいのイシューは @shimizukawa アイコンが表示されています。
今回はその轍を踏まないようにアカウントを作ろうとしたのですが、残念ながら失敗に終わりました。
github の規約上、1人につき free account は1件までという規約があるそうで、それに引っかかってしまいました*1。
というわけで、移行したイシューはすべて自分がオーナーになってます。
使い方は記事を見てください。
PR の移行
ツールが見当たらなかったこともあって、早々に諦めました。
CI 他の設定
まだやっていません。
今後の見通し
github に移動したことを受けてちょこちょこ進めていこうかと思っています。
ただ、Sphinx に割く時間がメインなのはしばらく変わらないと思います。
開発をぐいぐいと進めたいと思ってる人は、PR を投げるなりメンテナに立候補するなりしてください。
*1:知らずにトライしてしまい、サポートの方に余計な手間を掛けさせてしまいました。申し訳ない。
僕自身のスポンサーシップをはじめました
タイトルのとおりです。僕を支援していただくためのスポンサーシップをはじめました。
僕の OSS 活動のスポンサーを募集します。ご協力よろしくおねがいします! / @tk0miya のスポンサー募集 https://t.co/RqC8goNqjR
— Takeshi KOMIYA (@tk0miya) 2018年4月16日
おかげさまでとても多くの方に賛同していただき、かなりの額を支援していただきました。
Sphinx やら blockdiag やら、自分が関わっているプロダクトが多くの人に使われている結果なのだと思うと、これからも継続していこうと思いを新たにしました。
ここでは、スポンサーシップを初めたときの自分の考えをまとめておこうかと思います。
なぜはじめたのか
gist にも書いたように、お茶代の捻出が目的です。
Sphinx のメンテナをやるようになってから、ちょくちょく喫茶店で開発をするようになりました。
通勤の電車の中や自宅でも活動しいますが、休日はまとまった時間を使うために近所の喫茶店にこもることが多々あります。
集中しやすいとか、気分転換とか、いくつかの要素があるんじゃないかと思っています。
ありがたいことに僕の OSS 活動にはあまり費用が掛かっていません。
最近は GitHub や Travis CI のように、いろんなサービスで OSS 向けに無料のサービス提供をしていますし、所属している会社(株式会社タイムインターメディア)が開発機材を貸与してくれています*1。確かにドメインの更新費用やちょっとしたサービス利用料(S3 やら DNS やら)があるにはあるのですが、ちょっとした持ち出しで済んでいました。
そんな低コストの活動の中で、ひとつだけ "それなりの額" が掛かっているのが喫茶店代なのです。
チリも積もれば、とはよく言ったもので、一杯ではたいしたことがない紅茶も、たくさん飲めば結構な額に積み上がるんですね。束で買ったコーヒーチケットが雄弁に語っています。
喫茶店で開発してるなんて贅沢してるなー、と自分でも思う部分があるのですが、開発がはかどっているのも実感としてあります。そこで、この費用を個人の持ち出しではなく、スポンサーという形で協力してもらえないかと今回呼びかけてみました。
なぜ個人へのスポンサーなのか
今回募集しているスポンサーシップは、個人に対するものです。
Sphinx プロジェクトや blockdiag プロジェクトで呼びかけているものではありません。
理想で言えば、Sphinx プロジェクトとして広く (海外からも) 支援を受けたほうが、金額も集まりやすいですし、より多くの開発者に還元することができそうです。では、なぜ今回はプロジェクトとしてのスポンサーシップにしなかったのでしょうか。理由はふたつあります。
ひとつは先ほど説明したように、そもそものモチベーションがお茶代の支援という、極めて個人的で、しかも目標額が低いものだったのもあり、プロジェクトとして呼びかけるのは仰々しすぎました。
もうひとつは分配の問題です。現在の Sphinx プロジェクトはかなり多くの部分を僕がカバーしているとは言え、他のメンテナも要所要所で手助けしてくれているのも確かです。プロジェクトとしてスポンサーを集めた場合は、彼らにも同様に支援がなされるべきです。それを考えると一気に事務コストが増えます。公平な分配とはなんなのか。予算管理が必要になるのではないか。また、国際送金や税金についても考えなくてはなりません。
こうしたことを考えたときに、プロジェクトとしてスポンサーシップを進めるのはあまりに手間がかかりすぎると考えたので、こちらの線で検討するのは早々に諦めました。こうした分野に知見がある方が手伝ってくれるのであれば、いつかはプロジェクト規模でできると良いですが、今はその時ではないと考えています (自分の可処分時間を考えても)。
OSS でお金をもらうことについて
正直なところ、自分が OSS でお金をいただくことについては、自分の中でもスッキリはしていません。
自分ではない誰かが対価を得ることや、寄付を受けることについては気にならないのですが、いざ自分になると…という謎の感情があります。
あまり意識をしたことはないのですが、自分の中では OSS 活動は奉仕活動に近い、無償の活動だという思い込みがあるのかもしれません。一方で、それぞれの開発者のリソースは有限ですから、その活動は何かしらの形で讃えられてもおかしくないし、OSS でうまく稼げるのであればそれはそれでよい、とする見方も同居しています。
他者に対しては継続的でよいやり方だ、と褒め称える一方で、自分の場合はその部分にブレーキを踏んでいるのかもしれません。正直、自分でもなんでそんな考え方になっているのか、うまく説明できません。
もしかすると、対価を得てしまうと責任が発生するのではないかと恐れているのかもしれませんね。
最終的には半年以上悩んで、はじめて見ることにしました*2。
責任感
ということで、責任感はあります。
プロジェクトへの支援であればまだしも、僕個人への支援ですので、もし1年間遊び呆けてしまったら、スポンサーに向けて顔向けできない、というプレッシャーはあります。
急に仕事が忙しくなってしまったら、Sphinx の開発に飽きてしまったらどうしよう、みたいな考えも頭によぎります。
とはいえ、そんなことを心配し続けても仕方がありませんし、そういうぼんやりとした不安はねじ伏せて、前に進むだけです。
いままでも Sphinx のメンテナであることのプレッシャーは多少なりともありましたし、忙しかった時期も遊んでいた時期も含めて、年間通じてメンテナンスし続けていたわけですしね。
お金をもらっていても、もらっていなくても、やることそのものは変わりません。
ということで、顔の皮を厚くしてこれまでのペースで "ほどほどに" やっていこうと思います。
スポンサーシップのおかげで「より速く前に進む」のではなく、これまでのペースを維持するということに捉えて、プレッシャーにしないように意識していこうと思います*3。
ちなみに、6月にはワールドカップがあるので、その時期は活動が鈍るのは決定しています。あしからず。
申し訳無さ
つらつらと吐露していくと、他のメンテナ、他の OSS 開発者への申し訳無さみたいなものはあります。
それぞれ自分の時間や、何かしらの費用を持ち出しで OSS への貢献をしているのに、自分だけスポンサードされてよいのか、と思ったりもします。
ここも整理ができていないことのひとつです。なにか思うところがあったら教えてください。
指摘いただいたこと
sphinxがいろんなところに使われているのは認識しているけど @tk0miya さんとそれ以外のコミットの割合が70:30なのはOSSとしてどうかと思ってるより喫茶をおごるより他のデベロッパーのアクティビティを増やしていく方向に持っていたほうがガバナンス的にはいいと思うのだ。https://t.co/iIrPp8Oa4Y
— Takuya Noguchi (@tn961ir) 2018年4月17日
おっしゃるとおりです。
いまの Sphinx プロジェクトはひとりに作業が偏ってるのであまり健全とは言えません。
過去を振り返っても、作者の Georg が開発していた時期、 @shimizukawa が引き継いで*4メンテナンスしていた時期、そして今、とどの時期もメインのメンテナが作業の大部分をしているというプロジェクトの構造は大きく変わっていません。
ですので、今の時点では協力してもらうべき「他のデベロッパ」がほとんどいないというのがそもそもの問題です。
ドキュメントという地味な分野は人気がないのか、あまり開発に参加したいという人が少ないのです。
ですから、あらためて声を大にしていいます。
Sphinx プロジェクトではメンテナを募集しています。
未経験者歓迎です。
イシューの切り分け、バグの再現確認、ドキュメントの更新、使い方の質問へのフォローアップなどなど、Sphinx の内部構造を知らなくてもできる作業も山ほどあります。
メンテナには日本人が多いので、日本語での相談なども気軽にできます。
興味がある方は声を掛けてもらえるとありがたいです。
税金
こういうこと書くと水を指すようだけど、インターネットにおおっぴらにやってる人も見かけるから書いとくと、日本の税法で個人への「寄付」が成立する条件は厳しくて、たいていの場合「贈与」になって、貰った側は一時所得となるので、金額が大きくなる可能性があったら注意した方がいい。
— Yoshifumi Yamaguchi (@ymotongpoo) 2018年4月17日
別に「寄付やめろ!」って言ってるわけじゃなくて、注意しないと問題が起こる可能性があるよ、ってのを言ってるだけなので。もっともそこまで支援が集まるようであれば万々歳で、たいていはそんなにでかくならないとは思うので。あと貸与の形にできるものはそのほうがいいこともあるかもしれない。
— Yoshifumi Yamaguchi (@ymotongpoo) 2018年4月17日
そのとおりですね。
寄付額が年間 110万円を超えると贈与税がかかりますので、もし他にスポンサーシップをはじめる人がいたらご注意ください。
自分の場合は問題なさそうです。
まとめ
- スポンサーシップをはじめました
- おちこんだりもしたけど、私は元気です
- スポンサーは引き続き募集中です
Sphinx 10周年に寄せて #sphinx10th
本日、Sphinx-1.7.2 をリリースしました。いくつかのバグが修正されているので、試してみてください。
pypi.python.org
さて、リリースするまですっかり忘れていましたが、本日 3月21日は Sphinx の誕生日です。しかも、なんと 10周年です。
Release 0.1.61611 (Mar 21, 2008) ================================ * First public release.
Sphinx と僕の (だいたい) 10年間
僕が Python を使いはじめた頃から、既に Sphinx はよく使われていたので、かなり古くからあるツールだと思っていたのですが、実は 僕の Python 暦(2010年ごろ)とそんなに変わらないのですね。実際、Python を使いはじめた頃に 0.6.6 を使ってみたり、1.0 のリリースパーティに参加したりした覚えがあって、自分の記憶と CHANGES が一致しています。
sphinx-users.jp
その後、僕は blockdiag シリーズを作り、Sphinx 拡張職人になり、そして Sphinx のメンテナになり…とドキュメンテーションツールに関わり続けてきました。
Python をはじめてから、ずっと Sphinx とその周辺ツールにかかわっていますし、Sphinx を作るために Python を覚えたと言っても過言じゃないかもしれません。
すくなくとも、今では Sphinx が僕のホームであることは間違いありません。
なんとなく Python を使いはじめただけだというのに、なんとも不思議なことです。
この10年、Sphinx は僕の人生を巻き込んで前に進んできました。
毎日英語の読み書きをさせられたり、書籍を書くことになったり、雑誌に寄稿したりと、Sphinx に関わってから僕の生活は一変しました。
Sphinx のおかげで知り合った友人もたくさんいます。Google さんにも表彰されました。
まさか僕が関わっているソフトウェアがあの Debian に収録されていて、さらにカーネル、Python、その他諸々のドキュメントを支えているというのは想像もつかなかったことです。
決して派手ではないですが、Sphinx は僕を大きく変えたのです。
10years
10年前はまだ Sphinx や Python に出会う前で、何者かになりたいというワナビーだった頃です。
10年後のいまは実用的なソフトウェアのメンテナとして活動しています。
もしかすると、夢を叶えてなりたかったものになれたのかもしれません。
もしかすると、適当なところに居着いてしまっただけかもしれません。
かつては自分のやりたいこと、好きなことが選べる可能性を秘めていました。
いまは新しいものに触る時間は取れないし、アイディアがあっても完成させることもなかなかできません。
前に進んだのか、先細ったのか。
そのあたりは僕にもわかりませんが、きっとこの先 10年も Sphinx はそこにあるでしょう。
ソフトウェアがあるかぎり、ドキュメントは必要とされ続けるでしょうから。
あれから10年も。これから10年も。
10年前の自分が今の自分を想像できなかったように、10年後の自分が Sphinx とどう関わっているのかは想像がつきません。
でも、願わくば、なんらかの形で Sphinx と付き合っていけると良いな、と今は思っています。
これからも、きっと Sphinx は前に進んでいることでしょう。来年には Sphinx 2.0 がリリースされる予定です。
次の10年も、Sphinx が多くの開発者の手助けできることを祈って。
おめでとう、Sphinx。ありがとう、Sphinx。
#ポエム *1
Re: Markdownにmetaタグを入れる
つい最近、こんな記事が出ていました。
kamekokamekame.net
いいですね、コミュニティ。さっと拡張を書いてくれる人に優しさを感じます (自画自賛)。
markdown の拡張子は?
さて、この記事では source-read イベントをフックして md_prolog を実現しました。
でも、このコード、よく読むとイベントハンドラで filename.endswith('.md') とか決め打ちしていますね。
これでよいのでしょうか?
適当にぐぐってみると、こんなやりとりが見つかります。
superuser.com
.markdown とか .mkd とか、いろいろ使ってる人がいるんですね。
先ほどのコードは完璧ではありません。
Sphinx における markdown の拡張子
Sphinx では source_parsers の設定で、Markdown パーサを有効にすることが多いですよね*1。
source_parsers は conf.py にこんな感じで定義します。
from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md']
source_parsers 変数に「拡張子」と「パーサクラス」のペアを列挙します。
そして、source_suffix に対象となる拡張子のリストを並べます。
ここの設定を工夫することで、好みの拡張子を割り当てることができます。
任意の拡張子を考慮した md_prolog
さて、このように Sphinx では任意の拡張子を Markdown 文書として扱うことができます。
これに対して、冒頭の記事で紹介されているコードは対応できていません。
拡張子がハードコードされているため、設定によっては正しく動きません。
これに対応するには次のようなコードを書きます。
from recommonmark.parser import CommonMarkParser def on_source_read(app, docname, source): extensions = tuple([ext in (ext, parser) in app.config.source_parsers.items() if parser is CommonMarkParser]) filename = app.env.doc2path(docname) if filename.endswith(extensions): source[0] = app.config.md_prolog + "\n\n" + source[0]
このコードでは source_parsers の値を元に CommonMarkParser が処理する拡張子のファイルかどうかを判定しています。
ちょっとわかりづらいコードになっていますが、これは無事に動くはずです。
いまやほとんどの人は .md を使っているような気もするのですが、つい .markdown を使いたいひとや .mkd 派の貴方はこのコードを使ってみると良いでしょう。
オライリーへの入稿用の Sphinx拡張、sphinxcontrib-getstart-sphinx をリリースしました。
いつぞやの記事で「Sphinx をはじめよう 第2版」を書いた話をしたのを覚えてらっしゃいますか?ちなみに、オライリーさんのページはこちらです。以前に紹介したときは、紙媒体はイベントなどのオフラインでの購入に限定されていたのですが、いまでは通販でも手に入るようです。
電子書籍も好評発売中ですので、興味がある方はぜひとも見ていただければ、と思います。
www.oreilly.co.jp
さて、宣伝から話を戻しましょうか。
オライリーマニアのみなさんに於かれましては、オライリー・ジャパンさんの電子書籍の制作に Re:VIEW が深く関わっているのは既にご存知かと思います(参考:Community Blog - オライリー・ジャパンのePUBフォーマットを支える制作システム)。
この本の出版の際も、Sphinx で書かれた原稿を Re:VIEW に変更し、レビューや校正の段階では Re:VIEW 原稿を修正するというステップを踏んでいました。Sphinx をメンテしていて、reStructuredText に慣れ親しんだ身としては、ちょっと残念な気分でした。
Re:VIEW 記法に慣れていないというのもありますし、来るべき(?)第3版のために、reSTの元原稿も同時に変更していたというのもあり、Re:VIEW で原稿をいじるというのがちょっと負担だったのは確かです。reviewbuilder などによって、こうしたインピーダンスミスマッチは減ってきているとはいえ、いまだに乗り越えなくてはならない壁が残っていたのが、この書籍の制作過程でした。
さて、ここで黙っていたら男がすたるってもんですよね。Sphinx 拡張メイカー (自称)の名にかけて、こういう問題は拡張のちからでねじ伏せなくてはなりません。
というわけで、いつものごとく Sphinx 拡張を作りました*1。それが sphinxcontrib-getstart-sphinx です。
この拡張は、README に
sphinxcontrib-getstart-sphinx is a collection of Sphinx extensions to build Sphinxをはじめよう 第2版 (Getting Started with Sphinx 2nd Edition).
とあるように、Sphinx をはじめよう 第2版 のビルド用に作られた拡張群です。当初は sphinxcontrib-oreillyjapan にしようかと思ったのですが、流石にネームスペースが強すぎたので自重しました。
このパッケージには以下の拡張が含まれています。
- better_docref
- :doc: による参照を書籍向けのいい感じにする
- 具体的には『第1章「Sphinxとは」では…』のように章番号を付けた参照に置き換える
- column
- コラムを書くための column ディレクティブを追加する
- もちろん Re:VIEW への変換にも対応している
- footnote_relocator
- glossary_decorator
- glossary の用語部分を太字にする。これでキミのドキュメントもオライリー風だ!
- oreilly_review_table
- オライリーさんの内部ツールに合わせて Re:VIEW 出力形式をごにょごにょする
getstart_sphinx 拡張はアラカルト形式ですので、この中の任意のものを有効にすることもできます (もちろん全部有効にしてもオッケー)。
というわけで
オライリー・ジャパンで出版すると、 Sphinx で入稿できますよ!!! #sphinxjp
— Takeshi KOMIYA (@tk0miya) 2018年2月13日
というのが一歩進んだわけです。
Sphinx をはじめよう 第2版 ともどもよろしくお願いします。
*1:書き上げたまでは良かったものの、最近まで放置していたので、なんというか、ごめんなさい
Sphinx のバグを 1ヶ月で 80件以上クローズした件
1月の頭に合宿をやった勢いで、1月はひたすらメンテをやってました。
Sphinx-1.7 のリリースが近いのでひたすらチケットをちぎっては投げ、ちぎっては投げした結果、
1ヶ月で 83件ものチケットをクローズすることができました。ちなみに PR のマージは 100本超えました。
もちろん自分一人の力ではなくて、PR を投げてくれた人、レポートをしてくれた人を含め、色んな人に助けられての結果…なんですが、右下のコミットグラフにあるようにかなりの作業を僕がやっつけたので、Sphinx はオレが育てたと言っても過言ではありません。
おかげさまで 1.7.0 もどうにかリリースできる目処が付いてきましたし、とても嬉しいことにイシューの数が減少傾向にあります。2/3 18:00 現在、久しぶりに合算 700件の大台を割りました。
2.0 への道筋も見えてきた ということもあり、この後山場(?)を迎える Sphinx ですが、引き続きメンテを続けていこうと思っています。
とはいえ、このペースを維持すると流石にきついので、どこかでペースを落としたりサボったりしながら、ですけどね。
ちなみに、Sphinx プロジェクトは OSS に関わってみたい人、メンテナンスしてみたい人、などなど随時募集しています。
事実上のプロジェクトリーダーは日本人ですし*1、slack で日本語で会話できるコミッターが数人いますし、手伝いやすいかもしれませんよ!
Linux カーネルや Python に書籍の執筆など、多くの利用者がいるので、使われてる感もばっちりです。
興味がある人は僕あてにメンション投げたり、PR 投げたりしてみてください。
P.S.
ちなみにさっきのグラフだとイシュー減ってる感がありますが、実際には誤差です*2。
がんばっていきまっしょい。
Sphinx 開発合宿をしました。
合宿してきました。
当日や流れや施設の様子など、詳しいところは他の参加者の記事に譲ります。
takuan-osho.hatenablog.com
www.freia.jp
そういや今回全然写真撮ってないや。
感想
- 普段はひとりでやっているので、他の人を巻き込んでやれるのは新鮮
- SR+ なメンテナと会話することで、いくつかのチケットの方針が決まった
- 手がまわっていない、古いチケットのトリアージやクローズが進んだ
- Sphinx-1.7 での対応内容が整理された (ほぼ先送りした)
- Sphinx-2.0 のゴールが見えてきた
- いくつか新しい PR が飛んで来て助かった
普段はイシューの物量に押し流されて、どんどんノイジーになっているイシューリストがいくらか整理されましたし、
コアに関する議論の時間が取れたことで、止まっていたチケットが先に進むきっかけになりました。
ひとりで進めていくと、こうしたタスクが積もりに積もってしまうので、非常に助かりました。
(短時間で片付く軽めのタスク(質問とか、軽微なバグとか)ばかり片付くので、徐々に濃いやつばかり残っていく)
目で見てわかりやすいデータとして、Sphinx のイシューの増加がひさしぶりに減少傾向に転じました(一番右端のところ)*1。
施設の話
また、今回使った国立女性教育会館ですが、合宿向けの非常によい施設でした。
- 都内から近い (東上線沿線民だとさらに近い)
- 観光施設がないので気が散らない
- めっちゃ安い。一泊二日でフル活動しても 5,000円ちょい
- 5人部屋 + 夕食 + 朝食 + 会議室 2日弱
- アメニティに浴衣は含まれていないので要注意
ただ、このあたりの要素を合宿に求めてる人には向いてなさそうです。
- 温泉 (大浴場は夜しか使えず。深夜は不可)
- 近接のコンビニ (徒歩10分のところにあります。ドラッグストアもその近くに)
- 美味しいご飯 (施設内の食堂がメインです)
- インスタ映え
次回向けのメモ
- ネットワークの準備をしていこう
- 今回はネットワークまわりのことをほとんど考えずに行ったので、みんなテザリングだった
- 会議室は問題なかったが、居室は電波弱めだったみたい
- 有線からのブリッジがあると幸せそう
- ただ、IP がもらえないみたいな声も上がっていたので、多少の格闘が発生するかも
- 厳密には今回、ブリッジ? がひとつあったのだけどうまく設定できずに早々に諦めた
- 今回はネットワークまわりのことをほとんど考えずに行ったので、みんなテザリングだった
- ちゃんと寝よう
- 睡眠不足で死んでいるうさたーんが散見されたので (僕も眠かった)、粘らずほどよく寝るのが吉
まとめ
いくらか気になるところがないわけではないですが、開発合宿として使うにはよいところでした。
予約してくれた @shimizukawa ありがとう。
おかげで Sphinx の開発がいろいろ進みました。参加してくれたみんなありがとう。
他のひとたちの都合次第ではあるけど、年に 1-2回ぐらい行きたいところですね。
*1:当日夜計測の速報データです。今月の後半の進み具合によっては、グラフの向きが変わります。がんばりましょう。