Compatibility and Deprecations

This guide is the canonical 1.x compatibility, upgrade, and deprecation policy for Mailglass.

Use this guide when you need to answer any of these questions:

• Which Mailglass surfaces are the stable default path for 1.x
• Which older surfaces still work only as retained compatibility bridges
• What a patch, minor, or major release may change
• Which runtime, framework, database, and sibling-package combinations the repository currently proves

The stability inventories in docs/api_stability.md and mailglass_admin/docs/api_stability.md answer a different question: which package surfaces are stable, internal, or first-party-only. They are not the lifecycle policy by themselves.

Contract shape

Mailglass keeps a two-lane public posture for the 1.x line:

• stable lane: Mailglass.deliver/2, deliver!/2, deliver_later/2, deliver_many/2, deliver_many!/2, native Mailglass.Message setters such as to/2, from/2, subject/2, html_body/2, text_body/2, attach/2, and the escape hatch Mailglass.Message.update_swoosh/2
• compatibility lane: a deliberately small set of retained legacy bridges kept to make upgrades practical without promising that every historical path remains first-class forever

If you are starting fresh on 1.x, stay on the stable lane. The compatibility lane exists to help existing adopters land on 1.x without rewriting everything in one release.

Stable lane defaults

The stable lane is the path maintainers intend adopters to build on throughout the 1.x line.

• Delivery entrypoint: Mailglass.deliver*
• Message construction: native Mailglass.Message setters
• Advanced shaping when setters are not enough: Mailglass.Message.update_swoosh/2
• Support-contract verification: the repo-native checks under scripts/verify_support_contract.sh

The stable lane is the only lane that receives an affirmative compatibility promise across 1.x minor releases.

Compatibility lane

The compatibility lane is intentionally small. A retained path stays here only when the repository still documents a replacement, warning behavior, and a support horizon.

Examples of retained bridges for the 1.x transition:

• Mailglass.Message.new/2
• Mailglass.Outbound.send/2
• delivering a raw %Swoosh.Email{}
• the mix mailglass.upgrade.v0_2 codemod
• deprecated verify.phase_* aliases that forward to semantic verification aliases for one release cycle

Compatibility-lane support is not a promise that the older path remains the preferred API. It means the bridge still exists so adopters can migrate on a controlled schedule.

Release guarantees

Patch releases

Patch releases keep the documented 1.x stable lane intact.

Allowed in a patch release:

• bug fixes
• docs corrections
• additional tests or verification
• stricter warnings or docs around deprecated bridges
• security or correctness fixes that preserve the documented semantics as much as possible

Not allowed in a normal patch release:

• removing stable-lane APIs
• silently broadening or shrinking the support matrix beyond repo proof
• treating a retained compatibility bridge as stable without updating this guide

Minor releases

Minor releases may add new stable-lane APIs, new docs, new integrations, or new optional-dependency lanes.

Minor releases may also narrow the compatibility lane only when all of these are true:

• the affected path is already documented here as deprecated or compatibility only
• a replacement is already documented
• the support horizon documented here has been honored
• the change does not break the stable lane

Major releases

Major releases may remove deprecated bridges, revise guarantees, or redesign the support matrix. If a path is only promised through v2.0, assume that removal can happen no earlier than the first 2.x release.

Security and correctness exception

Mailglass keeps a narrow exception for security and correctness incidents.

If a documented behavior must change to fix a security issue, prevent data loss, restore signature correctness, or recover from a demonstrably unsafe contract bug, maintainers may ship the smallest safe change before the next major release. When that happens, the goal is:

• patch the unsafe behavior, not opportunistically redesign adjacent APIs
• document the exception in the changelog and maintainer docs
• provide the clearest available migration note or fallback path

This exception is intentionally narrow. It is not permission to bypass the stable-lane contract for convenience.

Warnings-as-errors guidance

Mailglass supports strict adopters that compile and test with --warnings-as-errors.

• Paths with explicit @deprecated metadata should be treated as migration work you should schedule before tightening your 1.x adoption baseline
• Silent legacy bridges may remain temporarily when this guide still documents them as compatibility-lane surfaces with a support horizon
• New code should prefer the stable lane even when a compatibility bridge still works

The repository itself proves this posture through docs and support-contract checks, including mix docs --warnings-as-errors, mix verify.support_contract.core, mix verify.support_contract.admin, and mix compile --no-optional-deps --warnings-as-errors.

Support matrix

This table is intentionally narrow. A row belongs here only if the repository proves it today through mix.exs, mailglass_admin/mix.exs, scripts/verify_support_contract.sh, or .github/workflows/ci.yml.

Optional dependency lanes

Optional dependencies are supported integration lanes when present, not part of the minimum runtime floor.

• oban
• opentelemetry
• mjml
• gen_smtp
• sigra

Those integrations are documented and compiled as optional dependencies in mix.exs. They are supported when present in a compatible adopter app, but the repo does not claim that every project must install them to remain inside the core 1.x contract.

Sibling-package policy

mailglass and mailglass_admin ship as matched siblings. For the 1.x contract, use matched release lines unless a future guide explicitly documents a different compatibility window.

mailglass_admin/mix.exs proves the current expectation:

• local development uses the repo path dependency
• published builds pin the exact sibling version

That is the current truth the repo can defend. Do not infer a broader cross-version compatibility story from shared source control alone.

What this guide does not promise

This guide does not promise:

• support for mailglass_inbound within the 1.x contract covered here
• broader Elixir, OTP, Phoenix, LiveView, Ecto, or Postgres ranges than the repository currently proves
• that every exported or reachable function is stable
• that deprecated bridges are equally preferred as the stable lane

How to use this guide

• Starting a new integration: stay on Mailglass.deliver* and native Mailglass.Message setters
• Upgrading from 0.x: use the canonical guides/upgrading-to-v1_0.md path and treat older migration guides as subordinate references
• Checking public surface promises: pair this guide with docs/api_stability.md and mailglass_admin/docs/api_stability.md
• Verifying repo truth: run scripts/verify_support_contract.sh

If a compatibility claim is not documented here or in the package stability inventories, do not assume it is part of the 1.x promise.