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

    • Build distribution packages: python -m build
    • Verify package contents
    • Upload to PyPI: python -m twine upload dist/*
    • Verify package installation from PyPI

  7. Post-Release

    • Announce release through appropriate channels
    • Bump version to next development version
    • Update roadmap and milestones for upcoming work
Nuanced