From bab304c620879f33a791bcd345772e243f8d16e7 Mon Sep 17 00:00:00 2001
From: Joel Male <joel@joelmale.com>
Date: Wed, 27 May 2026 21:50:54 +1000
Subject: [PATCH] docs: add UPGRADE.md and CHANGELOG.md

---
 CHANGELOG.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 UPGRADE.md   | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 CHANGELOG.md
 create mode 100644 UPGRADE.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..091a47b
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [3.0.0] - TBD
+
+### Added
+
+- **Storage driver system** (`CartDriver` interface, `CartManager`, `SessionDriver`, `DatabaseDriver`, `RedisDriver`, `NullDriver`, `MultiDriver`)
+- **`Cart::fake()`** - swaps the active driver for a `NullDriver` and returns a `CartFactory` for fluent test state seeding
+- **Assertion methods** on `Cart`: `assertContains()`, `assertCount()`, `assertTotalQuantity()`, `assertSubTotal()`, `assertTotal()`, `assertConditionApplied()`, `assertEmpty()`, `assertNotEmpty()`
+- **`CartFactory`** - fluent builder for seeding test cart state (`withItems()`, `withCondition()`, `withCoupon()`)
+- **`Coupon` abstract class** - extend to create first-class coupon objects that convert to `CartCondition`
+- **`TaxRule` abstract class** - extend to create first-class tax rules that convert to `CartCondition`
+- **`ShippingRate` abstract class** - extend to create first-class shipping rates that convert to `CartCondition`
+- **`Cart::coupon()`**, **`Cart::tax()`**, **`Cart::shipping()`** - accept first-class objects or raw `CartCondition`
+- **`HasCart` trait** - Livewire-aware trait with reactive `$cartItems`, `$cartTotal`, `$cartSubTotal`, `$cartCount` and proxy methods
+- **`ShareCartWithInertia`** - static class for sharing cart state via `HandleInertiaRequests::share()`
+- **`cart:install`** Artisan command - publishes config and scaffolds `app/Cart/` directory structure
+- **`cart:make:coupon`** Artisan command - generates a `Coupon` subclass stub
+- **`cart:make:tax`** Artisan command - generates a `TaxRule` subclass stub
+- **`cart:make:shipping`** Artisan command - generates a `ShippingRate` subclass stub
+- **`cart:make:driver`** Artisan command - generates a `CartDriver` implementation stub
+- **`cart:debug`** Artisan command - dumps current cart state (non-production only)
+- Laravel 13 support
+
+### Changed
+
+- `Cart` constructor now accepts a `CartDriver` instance instead of raw session/database storage
+- Config publish tag renamed from `config` to `cart-config`
+
+### Removed
+
+- `Wearepixel\Cart\CartSession` - replaced by the driver system
+
+## [2.1.1] - 2026-05-27
+
+### Fixed
+
+- PHP 8.4 deprecation warnings from Mockery implicit-nullable parameters in test bootstrap
+- Upgraded CI runners from deprecated `ubuntu-20.04` to `ubuntu-latest`
+
+### Changed
+
+- `pestphp/pest` upgraded from `^3.0` to `^4.7`
+
+## [2.1.0] - 2024-01-01
+
+### Added
+
+- Laravel 12 support
+
+## [2.0.0] - 2023-01-01
+
+### Added
+
+- Initial v2 release
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..aa73c99
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,60 @@
+# Upgrade Guide
+
+## v2.x to v3.0
+
+### Breaking changes
+
+#### Constructor signature
+
+`Cart` no longer accepts a raw session/database storage object as its first constructor argument. It now requires a `CartDriver` instance. If you were resolving `Cart` directly (not via the service container), update your instantiation:
+
+**Before:**
+
+```php
+new Cart($sessionStorage, $events, 'cart', $sessionKey, $config);
+```
+
+**After:**
+
+```php
+use Wearepixel\Cart\Drivers\SessionDriver;
+
+new Cart(new SessionDriver($session, $sessionKey), $events, 'cart', $config);
+```
+
+Applications that use the service container (the normal case) are unaffected - `CartServiceProvider` handles this automatically.
+
+#### Publish tag renamed
+
+The config publish tag changed from `config` to `cart-config` to avoid conflicts with other packages:
+
+**Before:**
+
+```bash
+php artisan vendor:publish --provider="Wearepixel\Cart\CartServiceProvider" --tag=config
+```
+
+**After:**
+
+```bash
+php artisan vendor:publish --provider="Wearepixel\Cart\CartServiceProvider" --tag=cart-config
+# or simply:
+php artisan cart:install
+```
+
+#### CartSession removed
+
+`Wearepixel\Cart\CartSession` has been removed. It is replaced by the driver system. If you extended or referenced `CartSession` directly, switch to the appropriate driver (`SessionDriver`, `DatabaseDriver`, etc.).
+
+### Non-breaking additions
+
+The following are additive and require no changes to existing code:
+
+- **Storage drivers:** `SessionDriver`, `DatabaseDriver`, `RedisDriver`, `NullDriver`, `MultiDriver` - configure via `config/cart.php`
+- **CartManager:** resolves drivers by name, accessible via `app('cart.manager')`
+- **First-class objects:** `Coupon`, `TaxRule`, `ShippingRate` abstract base classes - optional, existing raw `CartCondition` usage continues to work
+- **Cart::fake():** returns a `CartFactory` backed by an in-memory `NullDriver` for testing
+- **Assertion methods:** `Cart::assertContains()`, `assertCount()`, `assertTotal()`, etc.
+- **HasCart trait:** Livewire reactive cart state
+- **ShareCartWithInertia:** static class for Inertia middleware integration
+- **Artisan generators:** `cart:install`, `cart:make:coupon`, `cart:make:tax`, `cart:make:shipping`, `cart:make:driver`, `cart:debug`