# Releases and migration

Track the documented BirdHouse Matchmaking SDK version and coordinate compatible service upgrades.

Source: https://birdhouse.tech/docs/releases/

This documentation is written for **Roblox SDK version 0.4.0**. The package name remains `floque/matchmaking`, and it is distributed through a private Wally registry.

Source changes become installable only after a package release. Registry publication and hosted deployment status are not established by this documentation. Confirm both before upgrading.

## SDK 0.4.0: environments

Version 0.4.0 requires an `environment` when constructing a client:

```luau
local client = MatchmakingClient.new({
    baseUrl = "https://matchmaking.example.com",
    environment = "prod",
})
```

The client stamps every new session with this canonical environment. Session-level overrides are rejected. The corresponding service enforces isolation outside the constraint tree, so relaxed rules cannot mix environments.

### Coordinated upgrade

1. Prepare the environment-aware API service, workers, monitoring, and game-server callers together. Configure the same environment allowlist across the service.
2. Pause new searches and drain or cancel old waiting work. Stop every old worker before relying on isolation.
3. Deploy the compatible service and update callers to SDK 0.4.0 with an explicit environment before resuming creates.
4. Keep existing ticket and match records available for their original retention windows. Legacy unlabeled work must stay separate from named environments.
5. Verify that same-environment tickets can match, cross-environment tickets cannot mix, and invalid or disallowed environments are rejected.

Do not mix old unrestricted workers with environment-aware workers. An older API service can discard the new field, while the new one rejects missing environments.

### Legacy responses

`Ticket.environment` and `Match.environment` are optional because previously created results may omit them. The SDK also accepts the reserved `_unlabeled` value in responses. Neither missing values nor `_unlabeled` can be used as a new client environment.

Confirm and cancel continue to use only the ticket ID. Per-environment counters begin with this release and cannot reconstruct historical activity whose source records have expired.

## Moving from SDK 0.2.0 to 0.3.0

The 0.3.0 lifecycle and retry changes remain part of the 0.4.0 contract:

- Client-generated ticket GUIDs require a compatible API service; deploy that support before upgrading the SDK.
- `canceling` is nonterminal. Use `canceled` for completed cancellation.
- `TicketId` is assigned immediately and no longer proves service acceptance.
- Invalid `CreateSession` input throws synchronously.
- `Failed` and retained `Error` report terminal failures.
- `Destroy()` ends active sessions with `client_destroyed`.
- Match delivery requires no acknowledgement. Retain the match for your game's own handoff retries.

Deploy fixed matched-ticket retention with the service so completed results remain available for the ten-minute retry window. Review [lifecycle](https://birdhouse.tech/docs/lifecycle/) and [errors](https://birdhouse.tech/docs/errors/) when updating existing handlers.

## Integration references

Use these public references to review the documented integration contract:

| Contract | Documentation |
| --- | --- |
| Package identity and version | [Installation](https://birdhouse.tech/docs/installation/) |
| SDK integration guide | [Quickstart](https://birdhouse.tech/docs/quickstart/) |
| Client options and data shapes | [Roblox SDK](https://birdhouse.tech/docs/roblox-sdk/) |
| HTTP requests and responses | [HTTP API](https://birdhouse.tech/docs/http-api/) |
| Matching behavior | [Constraints](https://birdhouse.tech/docs/constraints/) |

Verify the version deployed by your service operator instead of inferring release status from the documentation alone. Contact [support@birdhouse.tech](mailto:support@birdhouse.tech) if you need help confirming compatibility or package access.