5

Semantic Versioning Specificationの最初のポイントでは、互換性のあるソフトウェアはパブリック API を宣言する必要があると述べています。

gem がこのパブリック API をどのように確立するのか疑問に思っています。これは通常、readme (たとえば、 ActiveRecordを参照) を介して行われるようですが、パブリック API コードと残りのコードの間に厳密な境界を引いているようには感じられません。これをより適切に行う宝石の例はTwitter APIで、その公開 API コードをAPI ディレクトリに配置しますが、公開 API の configure メソッドはAPI ディレクトリの外のtwitter.rbで定義されているため、その行は灰色です。

セマンティック バージョニング (バンドラーのようなツールがあることを考えると、ほとんどの場合) に固執しようとする gem の潜在的な貢献者として、公開 API の一部であるメソッドとそうでないメソッドを知りたいと思います。もっとソースコードを調べる必要があるかもしれませんが、パブリック API を明確に定義するためのガイドラインはどこかにありますか?

4

1 に答える 1

5

パブリック API を定義する一般的な方法がいくつかあります。どちらを選択するかは、ほとんどが好みの問題です。

1 つの方法はドキュメンテーションです。どのプロトコルがパブリック API の一部であるか、およびそれらのプロトコルのコントラクトは何かをドキュメントに記載するだけです。YARD には、このための定義済みタグもあります。

別の方法はテストです。Merbがこれをやったと思います。パブリック API は、その RSpec テストで説明されました。プライベート部分も明らかにテストされましたが、それらのテストは別のディレクトリにありました。

これは、コードの変更とセマンティック バージョンの変更を結び付けることができるため、実際には非常に優れています。パブリック ディレクトリにテストを追加するたびに、マイナー バージョンを更新する必要があります。public ディレクトリのテストを削除または変更するたびに、メジャー バージョンを更新する必要があります。

またはその逆: マイナー リビジョン中にテストを変更または削除することはできません。

于 2013-04-16T13:46:58.887 に答える