Versioning

Pseudata’s core promise is deterministic, cross-language consistency: the same seed produces identical data across Go, TypeScript, Java, Python, and every other supported language.

This guarantee is only possible through strict version control.

When your frontend (TypeScript) and backend (Go) use different Pseudata versions with incompatible changes, you break the fundamental contract:

• Same seed produces different users
• Integration tests fail mysteriously
• Bug reports become unreproducible
• Demos show inconsistent data

Version compatibility isn’t a nice-to-have—it’s the foundation that makes Pseudata work.

Semantic Versioning

Pseudata uses Semantic Versioning strictly:

MAJOR.MINOR.PATCH
  |     |     |
  |     |     └─ Bug fixes (backward compatible)
  |     └─────── New features (backward compatible)
  └───────────── Breaking changes (incompatible)

Why strict adherence:

1. Predictability: You know immediately if an upgrade is safe
2. Trust: Patch updates never break your code
3. Communication: Version numbers carry semantic meaning
4. Automation: CI/CD can auto-update patch/minor versions safely
5. Ecosystem Health: Downstream projects can specify compatible ranges

Compatibility Rules

Same major version = Fully compatible:

• Same seed produces identical data
• Cross-language consistency maintained
• Existing code continues to work
• API contracts preserved
• Example: v1.0.0 ↔ v1.5.2 ↔ v1.12.3
• TypeScript v1.2.0 works with Go v1.5.0

Different major versions = Breaking changes:

• API signatures may have changed
• Output format may differ
• Seed behavior may be modified
• Cross-version consistency NOT guaranteed
• Example: v1.x.x ↔ v2.x.x may be incompatible

Language parity:

• TypeScript v1.2.0 ↔ Go v1.2.0 ↔ Java v1.2.0 ↔ Python v1.2.0
• Same features, same API (adapted to language conventions)
• Released simultaneously

Version Bumps

Major (Breaking Changes):

• Renaming public methods
• Changing parameter order
• Removing public methods or types
• Modifying seed behavior (different results for same seed)
• Changing generated data format or structure
• Localization resource changes (new/modified data in locale files)
• Adding or removing locales
• Different random number generation logic
• Example: gen.user({ locale: "en_us" }) → gen.user("en_us", { seed: 12345 })

Minor (New Features):

• Adding new generator methods
• Adding new data types (User, Address, Product)
• New utility functions
• New locales (backward compatible)
• Additional optional parameters
• Performance improvements that preserve output
• Example: gen.user() works, gen.product() added

Patch (Bug Fixes):

• Correcting unintended behavior
• Fixing crashes or errors
• Resolving edge cases
• README improvements
• Code comment corrections
• Code cleanup (no external changes)
• Example: gen.user({ locale: "" }) no longer crashes

Upgrade Safety

Always safe:

• Patch updates: 1.2.3 → 1.2.4
• Minor updates: 1.2.0 → 1.3.0
• Any same-major: 1.0.0 → 1.99.0

Require review:

• Major updates: 1.x.x → 2.0.0
• Test thoroughly before deploying
• Update all language SDKs together