Merge pull request #322 from online-judge-tools/design-doc

Add DESIGN.md

Author: kmyk

DESIGN.md

@@ -0,0 +1,85 @@
+# Design Doc
+
+link: [DESIGN.md](https://github.com/online-judge-tools/.github/blob/master/DESIGN.md) of [online-judge-tools](https://github.com/online-judge-tools) organization
+
+
+## Objective
+
+`oj-verify` コマンドは、競技プログラミングのためのライブラリを現代的な方法で管理する機能を提供する。
+特に、実際の競技プログラミングの問題を用いたテストを簡単かつ快適に実行できるようにする。
+
+副次的な機能として、`oj-bundle` コマンドは、複数ファイルを単一ファイルにまとめて、現代的な形で書かれたソースコードをオンラインジャッジに提出できるようにする。
+
+
+## Goals
+
+-   ユーザのライブラリの信頼性を向上させること
+    -   これにはドキュメントを書かせることも含む
+-   競技プログラミング界隈における「ライブラリ」を「スニペットの寄せ集め」から脱却させ、それぞれの言語における標準的なライブラリに寄せていくこと
+
+
+## Non-Goals
+
+-   ユーザのライブラリの機能性を向上させること
+    -   ライブラリ整備が楽しくなるような機能を追加することはあるが、あくまでバグがでにくくなる
+
+
+## Background
+
+競技プログラミング用のライブラリのテストは、実際にそれを利用する問題に提出してみて AC することを確認するという手法が一般的である。
+これをすることは「ライブラリを verify する」と呼ばれている。
+しかし、これはとても面倒な作業であり、大規模ライブラリになりファイル数が増えるとすべてきちんと実行するのは非現実的であった。
+
+`oj-verify` コマンドの登場と普及の前は、ほとんどすべての競技プログラミング用のライブラリにテストは書かれていなかったことに注意したい。
+そもそも、過去において、競技プログラミングの「ライブラリ」とは通常の意味のライブラリではなく、むしろ「スニペット集」と呼ばれるべきものであった。
+ライブラリを `#include` 文などの標準的な機能で呼び出すことはまったく不可能で、エディタのスニペット機能の利用しての丸ごと埋め込みが通例であった。
+
+
+### Coding styles
+
+TODO: もっと詳しく書く
+
+
+### End-to-end tests vs. unit tests
+
+競技プログラミングの文脈で end-to end tests や integration tests と unit tests の区別をするのは不適切である。
+
+TODO: もっと詳しく書く
+
+
+## Overview
+
+TODO: 書く
+
+
+## Detailed Design
+
+TODO: 書く
+
+
+## Security Considerations
+
+システムケースの取得にログインが必要なオンラインジャッジがある (現在は yukicoder のみ)。
+その利用にはアクセストークンの設定が必要であるが、ユーザの設定ミスによりこれが公開されるとインイデントとなる。
+設定方法のドキュメントで encrypted secrets を使うよう要求するようにする。
+
+
+## Privacy Considerations
+
+特になし。
+ユーザが自分から公開しているコードについてのツールである。
+
+
+## Metrics Considerations
+
+GitHub 上での検索結果 <https://github.com/search?q=online-judge-verify-helper+path%3A.github> からユーザ数のほぼ正確な値が得られる。
+個別の機能の利用状況についての統計は得られない。
+
+2020/09/20 時点では利用数はおよそ 100 個である。
+競技プログラミング用のライブラリを内製しているユーザの総数を取得することは難しいため、利用割合などついては不明である。
+
+
+## Testing Plan
+
+開発者による dogfooding を中心とする。
+実行結果が GitHub Pages として公開されるという性質により、大まかなテストはそれで十分であろう。