Nuanced follows a versioning scheme based on Semantic Versioning with inspiration from the pandas versioning policy.

​
Version Format

Nuanced version numbers follow the format: X.Y.Z
  • X (Major): Changes that break backward compatibility
  • Y (Minor): New features without breaking backward compatibility
  • Z (Patch): Bug fixes and minor improvements

​
Version Policy

  • Major Versions (X.0.0): Released when introducing incompatible API changes. We aim to minimize these disruptions and provide clear migration guides.
  • Minor Versions (0.Y.0): Released when adding functionality in a backward-compatible manner. This includes new features, extensions to existing features, and significant refactoring.
  • Patch Versions (0.0.Z): Released for backward-compatible bug fixes, performance improvements, and documentation updates.

​
Development Versions

Development versions will be denoted with a suffix:
  • Alpha: X.Y.Z.devN (for internal development)
  • Beta: X.Y.Z.betaN (for wider testing)
  • Release Candidate: X.Y.Z.rcN (final testing before release)

​
Deprecation Policy

  • Features will be deprecated rather than removed immediately
  • Deprecated features will raise warnings for at least two minor releases before removal
  • Removal will only occur in major version updates
  • The deprecation timeline will be clearly documented

​
Release Process

Nuanced follows this release process for creating and publishing new versions:
  1. Prepare Changes
    • Make and test changes to source code
    • Update documentation to reflect changes
    • Ensure test coverage for new features and bug fixes
  2. Update Documentation
    • Document your changes in CHANGELOG.md following the Keep a Changelog format
    • Update version numbers in documentation
    • Build and verify documentation
  3. Version Bump
    • Update your package’s version number in:
    • pyproject.toml
    • __init__.py (__version__ attribute)
    • Any other version-dependent files
    • Commit version changes with message “Bump version to X.Y.Z”
  4. Quality Assurance
    • Run complete test suite, if applicable
    • Verify documentation builds correctly
    • Conduct final code review
  5. Create Release
    • Tag release: git tag vX.Y.Z
    • Push tag: git push origin vX.Y.Z
    • Create GitHub release with:
      • Version as title
      • Changelog entries as description
      • Any relevant migration notes
  6. Publish Package
    • Prerequisites: API keys associated with 2FA-enabled accounts on TestPyPI and PyPI
    • Build distribution packages: python -m build
    • Verify package contents
    • Upload to TestPyPI: python -m twine upload --repository testpypi dist/nuanced-<version>*
    • Upload to PyPI: python -m twine upload --repository pypi dist/nuanced-<version>*
    • Verify package installation from PyPI
      • pip install nuanced
      • uv tool install nuanced
  7. Post-Release
    • Announce release through appropriate channels
    • Bump version to next development version
    • Update roadmap and milestones for upcoming work