docs: 新增 CHANGELOG、重寫 README、CLAUDE.md 加入文件更新規則

CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `CHANGELOG.md`.
+- Full `README.md`: overview, requirements, installation, configuration, usage of every API, error handling, development and release flow.
+- CLAUDE.md rule: every PR must also update `README.md` and `CHANGELOG.md`.
+
+## [2.1.0] - 2026-10-27
+
+### Added
+
+- `history_id:` option for `Client#create_orders!` and `Client#create_sales!`: attach a batch to an existing import history on the XDelivery side, so several calls merge into one history. A blank (`nil`, `""`, whitespace) value is treated as absent and surrounding whitespace is stripped.
+- `Response::Orders#history_id` (the history the batch was attached to; `nil` on a failed response).
+- Support for Ruby 3.3 and 3.4: `required_ruby_version >= 2.7`, explicit `ostruct` dependency and require.
+- GitHub Actions test matrix (Ruby 3.1.7, 3.3.12, 3.4.11) and `publish.yml` (RubyGems Trusted Publishing).
+- CLAUDE.md release rules.
+
+### Changed
+
+- The `rest-client` dependency now requires `>= 2.0` (needed for `RestClient::Exceptions::Timeout`).
+- `Rakefile` default task is now `t`.
+
+### Fixed
+
+- Request timeouts (`RestClient::Exceptions::Timeout`) used to be swallowed and surfaced as a confusing `NoMethodError` (`nil.code`). They are now raised as-is.
+
+## [2.0.3] - 2022-08-04
+
+### Fixed
+
+- Release fixes after 2.0.0 (2.0.2 was never published to RubyGems).
+
+## [2.0.1] - 2022-08-04
+
+### Fixed
+
+- Release fixes after 2.0.0 (version bump only).
+
+## [2.0.0] - 2022-08-04
+
+### Added
+
+- `Xdelivery.env` / `Xdelivery.env=` and `Xdelivery.production?` / `Xdelivery.test?`. In any environment other than `production` requests go to the staging API (`https://api.staging.xdelivery.io`).
+- `API::Base#base_url`, `PRODUCTION_BASE_URL` and `TEST_BASE_URL`.
+
+### Removed
+
+- `API::Base::BASE_URL` (replaced by the two constants above).
+
+## [1.0.2] - 2022-05-04
+
+### Added
+
+- Error handling for HTTP error responses: `Client::NotFound` (404), `Client::InternalServerError` (500), `Client::BadGateway` (502), `Client::ServiceUnavailable` (503), `Client::GatewayTimeout` (504) and `Client::UnknownResponse` (non-JSON or unexpected status).
+
+## [1.0.1] - 2020-04-22
+
+### Added
+
+- `Xdelivery.open_timeout`, `Xdelivery.read_timeout` and `Xdelivery.configure`.
+
+## [1.0.0] - 2019-10-21
+
+### Added
+
+- Shops API: `Client#get_shops!`, and the `shop_id` order / sale column.
+
+### Removed
+
+- Invoice settings API (`Client#get_invoice_settings!`, `API::InvoiceSettings`) and the `invoice_setting_id` invoice column.
+
+## [0.2.4] - 2019-07-31
+
+### Added
+
+- `Xdelivery::Callback` to verify XDelivery's callback `check_code`.
+
+## [0.2.3] - 2019-07-30
+
+### Added
+
+- `merchant_note` (system note) order and sale column.
+
+## [0.2.2] - 2019-07-18
+
+### Added
+
+- `company_title` invoice column.
+
+## [0.2.1] - 2019-07-17
+
+### Added
+
+- `invoice_setting_id` in the sales invoice params.
+
+## [0.2.0] - 2019-07-16
+
+### Added
+
+- Invoice settings API (`Client#get_invoice_settings!`) and the `invoice_setting_id` invoice column (both removed again in 1.0.0).
+
+## [0.1.6] - 2019-06-21
+
+### Fixed
+
+- Fix in the sales API.
+
+## [0.1.5] - 2019-06-20
+
+### Added
+
+- Sales API (`Client#create_sales!`).
+
+## [0.1.4] - 2019-06-13
+
+### Added
+
+- Invoice items (`items` invoice column).
+
+## [0.1.3] - 2019-06-12
+
+### Changed
+
+- Renamed the invoice type column.
+
+## [0.1.2] - 2019-06-12
+
+### Added
+
+- Invoice support for orders.
+
+## [0.1.1] - 2018-12-21
+
+### Added
+
+- Product update API (`Client#update_products!`).
+
+## [0.1.0] - 2018-11-16
+
+### Added
+
+- Initial release.
+
+[Unreleased]: https://github.com/superlanding/xdelivery-ruby/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/superlanding/xdelivery-ruby/releases/tag/v2.1.0
+[2.0.3]: https://github.com/superlanding/xdelivery-ruby/commit/b0b5776
+[2.0.1]: https://github.com/superlanding/xdelivery-ruby/commit/a82af2d
+[2.0.0]: https://github.com/superlanding/xdelivery-ruby/commit/8d10d3a
+[1.0.2]: https://github.com/superlanding/xdelivery-ruby/commit/e6a829e
+[1.0.1]: https://github.com/superlanding/xdelivery-ruby/commit/53a9a6c
+[1.0.0]: https://github.com/superlanding/xdelivery-ruby/commit/e4a25eb
+[0.2.4]: https://github.com/superlanding/xdelivery-ruby/commit/c64600a
+[0.2.3]: https://github.com/superlanding/xdelivery-ruby/commit/6a9a00e
+[0.2.2]: https://github.com/superlanding/xdelivery-ruby/commit/410ee7a
+[0.2.1]: https://github.com/superlanding/xdelivery-ruby/commit/82d7953
+[0.2.0]: https://github.com/superlanding/xdelivery-ruby/commit/2853d8c
+[0.1.6]: https://github.com/superlanding/xdelivery-ruby/commit/d6e1c7b
+[0.1.5]: https://github.com/superlanding/xdelivery-ruby/commit/463d97b
+[0.1.4]: https://github.com/superlanding/xdelivery-ruby/commit/22bd18d
+[0.1.3]: https://github.com/superlanding/xdelivery-ruby/commit/c5c5890
+[0.1.2]: https://github.com/superlanding/xdelivery-ruby/commit/5b36875
+[0.1.1]: https://github.com/superlanding/xdelivery-ruby/commit/42c5f6b
+[0.1.0]: https://github.com/superlanding/xdelivery-ruby/commit/f4b2c20

CLAUDE.md

@@ -7,3 +7,14 @@
 - 跳版規則（Semantic Versioning）：修 bug 跳 patch（x.y.Z）；新增相容功能跳 minor（x.Y.0）；不相容變更跳 major（X.0.0）。
 - 版號只改在 PR 裡。AI 帳號只能開 branch 與 PR，不得合併到 master；只有真人帳號可以合併。合併就等於批准發佈。
 - 不得為了讓測試通過而改變程式原本的行為。
+
+## 文件與更新紀錄（README / CHANGELOG）
+
+- **每一個 PR 都必須同步更新文件**：
+  - 只要行為、用法、設定、相依套件或支援的 Ruby / Rails 版本有變，就要更新 `README.md`。
+  - 一律要在 `CHANGELOG.md` 新增一筆條目（[Keep a Changelog](https://keepachangelog.com/zh-TW/1.1.0/) 格式，分類用 Added / Changed / Deprecated / Removed / Fixed / Security）。
+- `CHANGELOG.md` 的寫法：
+  - 沒有跳版號的 PR：寫在最上方的 `## [Unreleased]` 底下。
+  - 有跳版號的 PR：把條目寫在新的版本章節 `## [x.y.z] - YYYY-MM-DD`（日期為合併日），並同步更新檔尾的版本比較連結。
+  - 版本號必須與 rubygems.org 上實際發佈的版本一致，不得寫還沒發佈的版本。
+- 只改文件、CI 或 CLAUDE.md 的 PR 不需要跳版號，但仍要在 `CHANGELOG.md` 的 `Unreleased` 補一筆。