Document differences between versioningit, versioneer, setuptools_scm

[basnijholt]

I cannot find what the fundamental differences between these packages are precisely:

• versioningit
• setuptools_scm
• versioneer

@jwodder, would you be able to comment on this?

One difference at least is that setuptools_scm isn't aware of editable installs: https://github.com/pypa/setuptools_scm/issues/518

[jwodder]

• versioningit:

  • Primarily configured entirely though pyproject.toml (though there is support for using it via setup.py for advanced usage)
  • Supports Git, specially-prepared Git archives, and Mercurial
  • Supports configuring the version string format via templates in pyproject.toml
  • Supports writing the version and other information to a file in your project tree
  • Simple configuration is possible via the pyproject.toml file, and more complex configuration can be accomplished by writing custom "method" functions that are stored in either your project repository or a separate package

• setuptools_scm:

  • Configured through pyproject.toml, setup.py, or setup.cfg
  • Supports Git, specially-prepared Git archives, and Mercurial
  • Causes all files in your code repository to be included in sdists
  • Supports writing the version to a file in your project tree
  • The format of the version string can be configured by selecting from a number of built-in formats; custom formats can be defined via Python functions stored in the project repository

• versioneer:

  • Requires adding an autogenerated _version.py file to your project
    • When your project is built, this file is replaced with details on the project's version
  • Can be used either in "vendored mode", in which an autogenerated versioneer.py file is added to the root of your project, or in "build-time dependency mode", which uses pyproject.toml's build-system.requires
  • Configured through either setup.cfg or pyproject.toml
  • Requires setup.py to be present
  • Supports Git and Git archives
  • The format of the version string can be configured by selecting from a number of built-in formats; custom formats do not seem to be supported

[basnijholt]

Thanks a lot for your detailed overview! Over time I have used all alternatives I could find. So far versioningit is my favorite.

I just wrote a blog post about my favorite Python dev tools, and tl;dr: versioningit is one of them: https://www.nijho.lt/post/best-python-dev-tooling/