diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 04a6d0e..e84b207 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,9 @@ ## Overview - + ## Changes @@ -12,7 +15,6 @@ ## Checklist -- [ ] I have followed the code style guidelines - [ ] I have performed a self-review of my code - [ ] I have updated the documentation (if necessary) - [ ] I have added appropriate labels to this pull request diff --git a/AGENTS.md b/AGENTS.md index 926ac82..38172d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,7 @@ This file helps coding agents be productive in this repository. ## Docs Project documentation lives in [docs/development/quick-start.md](docs/development/quick-start.md). +For contributor setup and development workflow, see [docs/development/CONTRIBUTING.md](docs/development/CONTRIBUTING.md). ## Fast Commands diff --git a/README.md b/README.md index 929a958..21d5cfc 100644 --- a/README.md +++ b/README.md @@ -17,4 +17,6 @@ npm install -D algolia-uploader - Quick start (English): [docs/development/quick-start.md](docs/development/quick-start.md) - Quick start (Japanese): [docs/development/quick-start.ja.md](docs/development/quick-start.ja.md) +- Contributing (English): [docs/development/CONTRIBUTING.md](docs/development/CONTRIBUTING.md) +- Contributing (Japanese): [docs/development/CONTRIBUTING.ja.md](docs/development/CONTRIBUTING.ja.md) - Repository map: [docs/development/repository-map.md](docs/development/repository-map.md) diff --git a/docs/development/CONTRIBUTING.ja.md b/docs/development/CONTRIBUTING.ja.md new file mode 100644 index 0000000..2217fba --- /dev/null +++ b/docs/development/CONTRIBUTING.ja.md @@ -0,0 +1,69 @@ +# コントリビューティング + +このガイドは、このリポジトリに貢献する開発者向けです。 + +## 1. 開発環境の準備 + +- Node.js 22.22.1 を使用してください。 +- 依存関係をインストールします。 + +```bash +npm install +``` + +- 実行確認が必要な場合は、[quick-start.ja.md](./quick-start.ja.md) を参照して `.env` を準備してください。 + +## 2. ローカル開発とデバッグ + +CLI をローカル実行します。 + +```bash +npm run dev +``` + +入力ディレクトリと Algolia 認証情報は環境変数で指定します。 + +## 3. ビルド・Lint・テスト + +- ビルド: + +```bash +npm run build +``` + +- Lint: + +```bash +npm run lint +``` + +- Lint 自動修正: + +```bash +npm run lint:fix +``` + +- 単体テスト: + +```bash +npm test +``` + +## 4. 単体試験の方針 + +- 振る舞いを変更した場合は、必ずテストを追加または更新してください。 +- テストは決定的で独立した状態を保ってください。 +- push 前に `npm test` を実行してください。 +- pre-push フックでもテストが実行されるため、失敗は解消してください。 + +## 5. ワークフローとプルリクエスト + +- ブランチ運用とコミット規約は [git-workflow.md](./git-workflow.md) に従ってください。 +- プルリクエストの構成は [.github/PULL_REQUEST_TEMPLATE.md](../../.github/PULL_REQUEST_TEMPLATE.md) に従ってください。 +- 挙動や使い方を変更した場合は関連ドキュメントを更新してください。 + +## 6. 関連資料 + +- プロジェクト構成と責務: [repository-map.md](./repository-map.md) +- リリース手順（メンテナー向け）: [publishing.md](./publishing.md) +- 利用者向け実行手順: [quick-start.ja.md](./quick-start.ja.md) diff --git a/docs/development/CONTRIBUTING.md b/docs/development/CONTRIBUTING.md new file mode 100644 index 0000000..9d1617e --- /dev/null +++ b/docs/development/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing + +This guide is for developers contributing to this repository. + +## 1. Development environment setup + +- Use Node.js 22.22.1. +- Install dependencies: + +```bash +npm install +``` + +- For runtime checks, prepare `.env` as described in [quick-start.md](./quick-start.md). + +## 2. Local development and debugging + +Run the CLI locally: + +```bash +npm run dev +``` + +Use your local input directory and Algolia credentials through environment variables. + +## 3. Build, lint, and test commands + +- Build: + +```bash +npm run build +``` + +- Lint: + +```bash +npm run lint +``` + +- Lint with autofix: + +```bash +npm run lint:fix +``` + +- Unit tests: + +```bash +npm test +``` + +## 4. Unit test policy + +- Add or update tests for every behavior change. +- Keep tests deterministic and isolated. +- Run `npm test` before pushing. +- Pre-push hook also runs tests. Do not bypass failures. + +## 5. Workflow and pull requests + +- Follow commit and branch rules in [git-workflow.md](./git-workflow.md). +- Follow the pull request structure in [.github/PULL_REQUEST_TEMPLATE.md](../../.github/PULL_REQUEST_TEMPLATE.md). +- Update related documentation when behavior or usage changes. + +## 6. Related references + +- Project structure and ownership: [repository-map.md](./repository-map.md) +- Release process (maintainers): [publishing.md](./publishing.md) +- End-user execution steps: [quick-start.md](./quick-start.md) diff --git a/docs/development/quick-start.ja.md b/docs/development/quick-start.ja.md index b7b00ed..8d79e8d 100644 --- a/docs/development/quick-start.ja.md +++ b/docs/development/quick-start.ja.md @@ -1,16 +1,16 @@ # クイックスタート -このガイドでは、アップローダーをローカルで実行するための最小限の手順を説明します。 +このガイドでは、ライブラリ利用者がライブラリを実行するための最小限の手順を説明します。 ## 1. 依存関係をインストールする ```bash -npm install +npm install -D algolia-uploader ``` ## 2. 環境変数を準備する -ローカルでデバッグする場合は、自分の値を使用して `.env.local` ファイルを作成します。このファイルは Git の対象外であり、コミットしてはいけません。 +ローカルで実行する場合は、以下のような `.env` ファイルを作成します。 ```env ALGOLIA_APP_ID=1234abcd5768 @@ -21,10 +21,12 @@ DATA_DIR=path/to/dir 必要な環境変数は次のとおりです。 -- `ALGOLIA_APP_ID` -- `ALGOLIA_ADMIN_API_KEY` -- `ALGOLIA_INDEX_NAME` -- `DATA_DIR` +| 環境変数 | 説明 | +| --- | --- | +| `ALGOLIA_APP_ID` | Algolia の App ID です。 | +| `ALGOLIA_ADMIN_API_KEY` | Algolia の API Key です。インデックスを更新できるKeyであればAdmin API Keyでなくても構いません。 | +| `ALGOLIA_INDEX_NAME` | Algolia で使用している Index 名です。 | +| `DATA_DIR` | アップロードしたい JSON ファイルを格納しているフォルダです。JSON ファイル名を個別指定したアップロードは、まだサポートしていません。 | ## 3. 入力 JSON を準備する @@ -35,16 +37,14 @@ DATA_DIR=path/to/dir ## 4. アップローダーを実行する -```bash -npm run dev +`package.json`では以下のようなscriptで実行できます。 + +```json +{ + "scripts": { + "algolia": "algolia-uploader" + } +} ``` CLI が JSON ファイルを読み込み、レコードを Algolia にアップロードします。 - -## 5. テストを実行する - -ユニットテストでは環境変数をモックしているため、`.env.local` は必要ありません。 - -```bash -npm test -``` diff --git a/docs/development/quick-start.md b/docs/development/quick-start.md index 8b906c4..b1b2acd 100644 --- a/docs/development/quick-start.md +++ b/docs/development/quick-start.md @@ -1,17 +1,16 @@ # Quick Start -This guide summarizes the minimum steps to run the uploader locally. +This guide summarizes the minimum steps for library users to run the uploader. ## 1. Install dependencies ```bash -npm install +npm install -D algolia-uploader ``` ## 2. Prepare environment variables -For local debugging, create a `.env.local` file with your own values. This file is -ignored by Git and must not be committed. +For local execution, create a `.env` file like the example below. ```env ALGOLIA_APP_ID=1234abcd5768 @@ -22,10 +21,12 @@ DATA_DIR=path/to/dir The required variables are: -- `ALGOLIA_APP_ID` -- `ALGOLIA_ADMIN_API_KEY` -- `ALGOLIA_INDEX_NAME` -- `DATA_DIR` +| Environment Variable | Description | +| --- | --- | +| `ALGOLIA_APP_ID` | Your Algolia App ID. | +| `ALGOLIA_ADMIN_API_KEY` | Your Algolia API key. It does not need to be an Admin key as long as it can update the target index. | +| `ALGOLIA_INDEX_NAME` | The name of your Algolia index. | +| `DATA_DIR` | Directory that contains JSON files to upload. Upload by specifying individual filenames is not supported yet. | ## 3. Prepare input JSON @@ -36,16 +37,14 @@ Place JSON files in the directory specified by `DATA_DIR`. ## 4. Run the uploader -```bash -npm run dev +You can run the uploader through a script like this in your `package.json`: + +```json +{ + "scripts": { + "algolia": "algolia-uploader" + } +} ``` The CLI will read the JSON files and upload the records to Algolia. - -## 5. Run tests - -Unit tests use mocked environment variables and do not require `.env.local`: - -```bash -npm test -```