コンテンツにスキップ
Data Package Logo Data Package Logo データパッケージスタンダード
Blog

貢献する

非公式翻訳 (Unofficial translation). これはデータパッケージスタンダードの有志による日本語訳です。 正典は英語原典 datapackage.org 。未訳の箇所は英語の原文を参照してください。

データパッケージスタンダードに貢献する方法は数多くある。いくつか挙げる。

  • 標準を使う: 最良の貢献方法は、自分のプロジェクトでこの標準を使い、何がうまくいき何がうまくいかないかについてフィードバックを提供することである。

  • 広める: データパッケージスタンダードについて広めるのを手伝ってほしい。この標準を知る人が増えれば増えるほど、貢献できる人も増える。

  • 議論に参加する: あなたのアイデアやフィードバックを Data Package Discusions で共有してほしい。我々は課題と機能要望の優先順位付けに投票システムを用いている。

  • 問題を報告する: バグを見つけたり機能要望があったりした場合は、GitHub issue tracker に報告してほしい。着手しやすいよう、あらかじめ定義された issue テンプレートがいくつか用意されている。

  • リポジトリに貢献する: データパッケージスタンダードのリポジトリに貢献できる。そのプロセスの詳細については本ガイドを読んでほしい。

研究と開発

データパッケージスタンダードは、研究開発(research and development)モデルを用いて開発されている。これは、新しい機能や変更が協働的なやり方で提案・議論・実装される、反復的なやり方で標準が開発されることを意味する。

データパッケージスタンダードには、主たるフィードバックトラッカーが二つある。

  1. Data Package Discussions: ここは、データパッケージスタンダードに関する一般的な議論や新機能の提案が行われる場である。このフォーラムを使って、アイデアを共有したり、質問したり、フィードバックを提供したりできる。ディスカッションと投票の仕組みを通じて、コミュニティと Data Package Working Group は課題や機能要望の優先順位付けを手助けできる。ディスカッションは、機能の草案や実装の詳細を設計・共有するのに適した場である。おおまかに言えば、これは研究フェーズである。

  2. Data Package Issues: ここは、バグ・一般的な改善・特定の機能要望が追跡される場である。ここでの issue は、実行可能(actionable)で明確なスコープを持たねばならない。Data Package のメンテナーは、まず議論や投票が必要な issue を Discussions に移したり、実装が予定されていない issue をクローズしたりすることがある。おおまかに言えば、これは開発フェーズである。

ブランチとリリース

データパッケージプロジェクトは、二つの主要なブランチを用いる。

  1. main: これは公開のメインブランチである。本番の https://datapackage.org のウェブサイトはこのブランチからビルドされる。許可されるプルリクエストの種類は、ドキュメント更新・雑務的な改善・その他の軽微な変更である。

  2. next: これは開発ブランチである。新機能や変更はこのブランチで実装される。データパッケージは不変な公開プロファイル(immutable public profiles)モデルに従うため、プロファイルの更新を要するすべてのバグ修正もここに含まれる。

リリースモデル

新しいデータパッケージのバージョンをリリースする際は、このプロセスを用いる。

  • メンテナーは、next ブランチから main ブランチへの Release vX.Y という名前の新しいプルリクエストを作成する。このプルリクエストには、package.json のバージョン更新と、プロファイルを更新するために実行された npm run generate コマンドが含まれる。

  • リリースに含めるすべてのプルリクエストは、標準的なレビュー/投票プロセスに従って next ブランチにマージされるべきである。プルリクエストの一部として変更履歴(changelog)のエントリを含めることが推奨される。メンテナーはこれらのプルリクエストを “Squash and merge” 戦略でマージする。

  • Release vX.Y がリリース可能になったら、メンテナーは変更履歴の正しさを確認し、必要であれば衝突を解消したうえで、“Create a merge commit” 戦略で next ブランチを main ブランチにマージする。ウェブサイトのビルドが成功した後、メンテナーは、リリースされたバージョンのリリースノートとともに変更履歴のエントリをリンクした、新しいタグとリリースを GitHub 上に作成する。

コードベースへの貢献

データパッケージプロジェクトは Astro Starlight 静的サイトジェネレーターをベースとしており、ビルドプロセスに TypeScript/Node.js を用いている。コードベースに貢献する手順は次のとおりである。

  1. リポジトリをフォークする: リポジトリページの右上隅にある “Fork” ボタンをクリックする。
  2. リポジトリをクローンする: フォークしたリポジトリをローカルマシンにクローンする。
  3. 依存関係をインストールする: npm install を実行してプロジェクトの依存関係をインストールする。
  4. 開発サーバーを起動する: npm start を実行して変更をローカルで確認する。
  5. 変更を加える: コードベースに変更を加える。
  6. プロファイルを生成する: npm run generate を実行してプロファイルを生成する。
  7. スタイルを整形する: npm run format を実行してスタイルを整形する。
  8. テストを実行する: npm test を実行してテストを実行する。
  9. 変更をコミットする: フォークしたリポジトリに変更をコミットする。
  10. プルリクエストを作成する: フォークしたリポジトリから、メインリポジトリの適切なブランチへプルリクエストを作成する(上記のブランチモデルを参照)。

プルリクエストが作成されると、Data Package のメンテナーによってレビューされる。GitHub の自動化(Automation)は、新しいプルリクエストごとにライブプレビューサイトを作成する。プルリクエストが承認されると、メインリポジトリにマージされる。

なお、本プロジェクトは二種類の生成成果物を用いる。

  1. npm run generate: このコマンドは profiles フォルダからプロファイルを生成し、仕様内のプロファイルバージョンを同期する。profiles フォルダ内の YAML/JSON ファイルを変更した後はこのコマンドを実行する必要があり、その出力はリポジトリにコミットしなければならない。

  2. npm run build: このコマンドはプロジェクトをビルドし静的サイトを生成する。このコマンドは自動化によって実行され、その出力はリポジトリにコミットされない。貢献者としてこのコマンドを実行する必要はないが、本番モードでビルドされたサイトをローカルでデバッグするために npm run preview を使うことはできる。

後方互換性

本節では、データパッケージ仕様における後方互換性のルールを概説する。

  1. 妥当である既存の datapackage.json が、将来において無効になってはならない (MUST NOT)。
  2. 新しい datapackage.json は、ソフトウェア実装が(まだ)仕様の最新バージョンをサポートしていないために、無効であってもよい (MAY)。

バージョニング

  1. データパッケージ仕様はバージョン管理される。これは、バージョンを上げずに変更が追加されていた 1.0 以降の新しい点である。
  2. データパッケージ仕様は全体として一括でバージョン管理される。すなわち、複数の変更が検討・議論され、追加または却下されたうえで、新しいマイナーバージョンとしてリリースされる。

プロパティの変更

  1. プロパティは type を変更してはならない (MUST NOT)。
  2. プロパティは追加の type(配列)を許容してもよい (MAY)。
  3. プロパティが required になってはならない (MUST NOT)。
  4. プロパティはオプションになってもよい (MAY)。例: https://github.com/frictionlessdata/datapackage/pull/7
  5. プロパティは enum を追加してはならない (MUST NOT)。
  6. プロパティは enum を削除してもよい (MAY)。例: https://github.com/frictionlessdata/specs/pull/809
  7. プロパティは enum の値を削除してはならない (MUST NOT)。
  8. プロパティは enum の値を追加してもよい (MAY)。

テーブルスキーマの変更

  1. フィールド型はデフォルトの format を変更してはならない (MUST NOT)。
  2. フィールド型は format のパターンオプションを削除してはならない (MUST NOT)。
  3. フィールド型は format のパターンオプションを追加してもよい (MAY)。

新しいプロパティ

  1. 新しいプロパティは(一般ルール 2 により)datapackage.json を無効にしてもよい (MAY)。例: https://github.com/frictionlessdata/datapackage/pull/24
  2. 新しいプロパティは required にできない (CANNOT)。

削除されたプロパティ

  1. プロパティの削除は(一般ルール 1 により)datapackage.json を無効にできない (CANNOT)。