Asciidoctor VS Code拡張で学んだ、実装からAPI設計までの道のり
OSS（オープンソースソフトウェア）へ貢献したいと思っていても、
- 何から始めればよいか分からない
- いきなり大きな機能を提案するのは難しい
- 英語でIssueを書くのはハードルが高い
と感じる人は多いのではないでしょうか。
私も同じでした。
今回、Asciidoctor VS Code拡張への貢献を通して、
OSSへの貢献とは、コードを書くことだけではない
ということを実感しました。
この記事では、次の3つを題材に、
- 実装してみる
- 課題を見つける
- Issueで提案する
- コミュニティと議論する
- より良い設計へ育てる
というOSSらしい開発の流れを紹介します。
- https://github.com/asciidoctor/asciidoctor-vscode/pull/569
- https://github.com/asciidoctor/asciidoctor-vscode/issues/1033
- https://github.com/asciidoctor/asciidoctor-vscode/pull/1035
全体の流れ
今回の流れを図にすると、このようになります。
PR #569
workspaceからAsciidoctor.js extensionsを読み込めるようにした
↓
セキュリティ・配布方法に課題があることが分かった
↓
Issue #1033
VS Code拡張として登録できるAPIを提案
↓
コミュニティで議論
↓
PR #1035
より良いAPI設計として実装
最初からAPIを提案したわけではありません。
まずは実装し、使ってみたことで新しい課題が見えてきました。
まずは「動くもの」を作る
最初に送ったPRはこちらです。
このPRでは、
workspace内の .asciidoctor/lib に配置した Asciidoctor.js Extension を読み込めるようにする
という機能を追加しました。
これにより、VS Codeのプレビューやエクスポートでも独自のAsciidoctor拡張を利用できるようになりました。
当時は、
「Asciidoctor.js Extensionを使えるようにしたい」
という目的だけで十分でした。
まずは動くものを作る。
OSSでは、この第一歩がとても重要だと思います。
実装すると、新しい課題が見えてきた
PR #569 のレビューでは、多くの議論がありました。
その中でも大きかったのが、
workspace内のJavaScriptを実行することへのセキュリティ
です。
例えば、
- プロジェクトを開くだけでコードを実行してよいのか
- ユーザーに確認を求めるべきではないか
といった議論が行われました。
実際、このPRでもユーザー確認の仕組みなど、安全性について何度もレビューを受けました。
つまり、
「動くこと」と「安心して使えること」は別問題
だったのです。
配布方法にも課題があった
もう一つ気付いたのが、
拡張の配布方法です。
workspace方式では、
各プロジェクトに
.asciidoctor/lib
を置く必要があります。
これはプロジェクト固有の拡張には便利ですが、
私が作りたかったのは、
VS Code Marketplaceからインストールできる拡張
でした。
VS Code拡張として配布できれば、
- インストール
- 更新
- バージョン管理
- 信頼モデル
をVS Codeに任せられます。
こちらの方が、多くのユーザーにとって扱いやすいと考えました。
IssueでAPIを提案した
そこで作成したのが、
です。
ここでは、
他のVS Code拡張からAsciidoctor.js Extensionを登録できるAPI
を提案しました。
ポイントは、
Asciidoctor VS Code拡張自身は汎用のままにし、
各機能は別のVS Code拡張として追加できるようにすることです。
つまり、
Asciidoctor VS Code
↑
API
↑
自分の拡張
という構成です。
この構成なら、
Asciidoctor VS Code本体はシンプルなまま、
さまざまな拡張を追加できます。
APIは「最小」がよい
Issueを書いていて意識したことがあります。
それは、
APIは小さいほどよい
ということです。
最初は、
「あれもできたら便利」
「これも公開してほしい」
と思っていました。
しかし、
公開APIは一度公開すると長期間保守する必要があります。
そのため、
最終的には
Asciidoctor.js Extensionを登録する
という最小限のAPIだけに絞りました。
この考え方はOSSならではだと思います。
コミュニティと議論すると、もっと良い設計になる
Issueで議論していると、
メンテナーから
「もっとVS Codeらしい方法がある」
という提案をいただきました。
それが、
です。
ここでは、
VS Code標準のMarkdown拡張の仕組みを参考にした
pull-based registration API
が提案されました。
私の提案とは少し違いましたが、
- lazy activation
- エラー分離
- 拡張IDによる管理
- 将来の拡張性
など、多くのメリットがありました。
「なるほど、その方がOSS本体としては良い設計だ」
と思いました。
OSSでは「自分の案」が採用されることがゴールではない
今回、一番印象に残ったことがあります。
それは、
自分の提案そのものが採用されることがゴールではない
ということです。
私が提起した課題は、
コミュニティで議論され、
メンテナーの知見が加わり、
最終的には
私が最初に考えていたよりも良いAPI
になりました。
これはOSSらしい、とても良い経験でした。
実際に自分の拡張で利用できた
完成したAPIを使って、
私は
asciidoctor-numbered-captions-vscode
を公開できました。
以前であれば、
workspaceへJavaScriptを配置する必要がありました。
しかし新しいAPIでは、
普通のVS Code拡張として配布できます。
つまり、
今回のAPIは、
私自身の拡張だけでなく、
今後Asciidoctor拡張を作る人全員が利用できる仕組みになりました。
今回学んだOSSへの貢献
今回の経験から学んだことは5つあります。
1. まず動くものを作る
実装すると課題が見えてきます。
2. 実装して終わりではない
レビューで初めて見える問題もあります。
3. Issueを書くことも立派な貢献
設計を整理し、
議論の土台を作ることも重要です。
4. メンテナーには別の視点がある
OSS全体を長く保守するための設計は、
利用者だけでは気付けないことがあります。
5. 一緒に育てることがOSS
最終的なAPIは、
私一人では作れませんでした。
コミュニティとの議論があったからこそ、
より良い形になりました。
おわりに
OSSへの貢献というと、
「すごいコードを書くこと」
を想像しがちです。
しかし今回の経験では、
一番価値があったのは、
実装をきっかけに課題を見つけ、
Issueで提案し、
コミュニティと一緒に設計を育てられたことでした。
もしOSSへ貢献してみたいと思っている方がいたら、
まずは小さな実装から始めてみてください。
そして、その実装で見えてきた課題をIssueとして提案してみてください。
その一歩が、思っている以上に大きな貢献につながるかもしれません。