# Versioning Policy
`hashavatar` is intended to be safe for deterministic avatar URLs.
## Stable Rendering Contract
Within a major release line, the project aims to keep avatar output stable for the same:
- `tenant`
- `style_version`
- identity hash algorithm
- `id`
- `kind`
- `background`
- `accessory`
- `color`
- `expression`
- `shape`
- `format`
- `size`
That means an application can cache and embed avatar URLs without expecting silent visual churn during normal minor and patch upgrades.
Callers that use the legacy `AvatarOptions` API implicitly use `accessory =
none`, `color = default`, `expression = default`, and `shape = square`.
## When Output May Change
Visual output may change when:
- you intentionally change `style_version`
- you intentionally change `tenant`
- you intentionally change the identity hash algorithm
- you adopt a new major crate release with documented breaking visual changes
- a narrowly scoped rendering bug fix is required and documented
## Recommended Production Strategy
- treat `tenant` as your product or environment namespace
- treat `style_version` as your avatar rollout version, for example `v2`
- use the default SHA-512 algorithm unless you have explicitly chosen and
documented another algorithm
- do not send raw user emails if you can avoid it
- prefer stable internal ids or a one-way hash as the public avatar id
## Regression Protection
The repository includes golden fingerprint regression tests. Those tests are meant to catch unintended visual changes before release.
## Cross-Platform Determinism
The current renderer uses floating-point geometry internally. Golden
fingerprints protect the release platform, but `hashavatar` does not yet claim
a formal bit-identical raster contract across every CPU architecture, compiler
backend, and optimization mode. Future core work should move critical geometry
to fixed-point arithmetic before making that stronger guarantee.