Document v2 migration guidance

Author: oschwald

CHANGELOG.md

@@ -1,8 +1,16 @@
 # 2.0.0 -
 
+- **BREAKING CHANGE**: Lookup methods now require `netip.Addr`, return typed
+  `Names`, and provide `HasData()` helpers while always populating
+  `Network`/`IPAddress` fields so network topology remains accessible.
+- **BREAKING CHANGE**: Struct field casing now matches MaxMind responses (for
+  example `IsoCode` → `ISOCode`), location coordinates use pointers, and JSON
+  tags rely on Go 1.24 `omitzero` support—upgrade your toolchain before
+  adopting v2.
+- Added `MIGRATION.md` with detailed guidance for upgrading from v1.
 - Updated dependency on `github.com/oschwald/maxminddb-golang/v2` to `v2.0.0`.
-- Add configurable `Option` helpers so `Open` and `OpenBytes` can accept
-  future options.
+- Added configurable `Option` helpers so `Open` and `OpenBytes` can accept
+  future options without forcing a v3 release.
 - **BREAKING CHANGE**: Removed deprecated `FromBytes` method. Use `OpenBytes`
   instead.
 

MIGRATION.md

@@ -0,0 +1,106 @@
+# Migrating to geoip2-golang v2
+
+Version 2.0 modernizes the public API, improves performance, and tightens
+parity with current MaxMind databases. This guide highlights the most important
+changes and shows how to update existing v1 code.
+
+## Upgrade Checklist
+
+1. **Update imports**
+
+   ```go
+   // v1
+   import "github.com/oschwald/geoip2-golang"
+
+   // v2
+   import "github.com/oschwald/geoip2-golang/v2"
+   ```
+
+2. **Switch to `netip.Addr`**
+
+   Lookup methods now take `netip.Addr` instead of `net.IP`. Use
+   `netip.ParseAddr` (errors on invalid input) or `netip.MustParseAddr` for
+   trusted literals. This avoids ambiguity around IPv4-in-IPv6 addresses and
+   removes heap allocations for most lookups.
+
+   ```go
+   // v1
+   ip := net.ParseIP("81.2.69.142")
+   record, err := db.City(ip)
+
+   // v2
+   ip, err := netip.ParseAddr("81.2.69.142")
+   if err != nil {
+       return err
+   }
+   record, err := db.City(ip)
+   ```
+
+3. **Adopt the new `HasData()` helpers**
+
+   All result structs have a `HasData()` method that ignores the always-filled
+   `Network` and `IPAddress` fields. Use it instead of comparing against zero
+   values.
+
+   ```go
+   record, err := db.City(ip)
+   if err != nil {
+       return err
+   }
+   if !record.HasData() {
+       // handle missing GeoIP data
+   }
+   ```
+
+4. **Use structured `Names` fields**
+
+   Localized names are now strongly typed instead of map lookups. Access the
+   language-specific struct field directly.
+
+   ```go
+   // v1
+   cityEn := record.City.Names["en"]
+   cityPtBr := record.City.Names["pt-BR"]
+
+   // v2
+   cityEn := record.City.Names.English
+   cityPtBr := record.City.Names.BrazilianPortuguese
+   ```
+
+   Supported fields include `English`, `German`, `Spanish`, `French`,
+   `Japanese`, `BrazilianPortuguese`, `Russian`, and `SimplifiedChinese`.
+
+5. **Expect `Network` and `IPAddress` on every result**
+
+   Each lookup populates the queried IP address and the enclosing network on
+   every result struct, even if `HasData()` returns false. Existing code that
+   depended on empty `Network` for “no data” should switch to `HasData()`.
+
+6. **Adjust renamed fields**
+
+   `IsoCode` is now `ISOCode` across all structs. Update code accordingly.
+
+   ```go
+   // v1
+   code := record.Country.IsoCode
+
+   // v2
+   code := record.Country.ISOCode
+   ```
+
+7. **Build with Go 1.24 or newer**
+
+   The module now depends on Go 1.24 features such as `omitzero` struct tags.
+   Update your toolchain (`go env GOVERSION`) before upgrading.
+
+## Additional Notes
+
+- `Open` and `OpenBytes` accept optional `Option` values, allowing future
+  extensions without new breaking releases.
+- The legacy `FromBytes` helper is removed. Use `OpenBytes` instead.
+- JSON output mirrors MaxMind database naming thanks to the new `omitzero` tags
+  and typed structs.
+
+Following the checklist above should cover most migrations. For edge cases,
+review `models.go` for field definitions and `example_test.go` for idiomatic
+usage with the v2 API.

README.md

@@ -38,6 +38,11 @@ Version 2.0 includes several major improvements:
 - **Go 1.24 Support**: Uses `omitzero` JSON tags to match MaxMind database
   behavior
 
+## Migration
+
+See [MIGRATION.md](MIGRATION.md) for step-by-step guidance on upgrading from
+v1.
+
 ## Usage
 
 [See GoDoc](https://pkg.go.dev/github.com/oschwald/geoip2-golang/v2) for