use versioningit

docs/source/index.rst

@@ -20,7 +20,7 @@ Starting repositories can be created from this template so you can focus on what
    * Basic testing structure with `PyTest <https://docs.pytest.org/en/latest/>`_
    * Automatic ``git`` initialization + tag
    * GitHub Hooks
-   * Automatic package version control with `Versioneer <https://github.com/warner/python-versioneer>`_
+   * Automatic package version control with `versioningit <https://versioningit.readthedocs.io/en/stable/index.html>`_
    * Sample data inclusion with packaging instructions
    * Basic documentation structure powered by `Sphinx <http://www.sphinx-doc.org/en/master/>`_
 

docs/source/usage.rst

@@ -125,5 +125,50 @@ To keep things clean and simple, we advise a few tips:
   for more information.
 
 
+5. Tagging versions of your code
+--------------------------------
+
+Tagging versions of your code is a good way to keep references
+to specific versions of your code that don't change.
+This is especially useful when you want to make a new code
+release. The ``cookiecutter`` uses `versioningit`_ to
+automatically determine your package's version based on
+git tags.
+
+By default, versioning will start from ``0.0.0``.
+You can install versioningit_ to check versioning it from commandline:
+
+.. code-block:: bash
+  
+  $ cd <my_package_directory>
+  $ versioningit .
+  0.0.0
+
+As you add commits, the versioning will automatically update with
+the commit hashes:
+
+.. code-block:: bash
+
+  $ versioningit .
+  0.0.0+1.g58bcaff
+
+To tag a version, use the following command:
+
+.. code-block:: bash
+
+    git tag -a 0.1.0 -m "Version 0.1.0"
+
+This will create a tag called ``0.1.0`` with the message
+"Version 0.1.0". You can then push this tag to GitHub with ``git push origin --tags``.
+
+After creating a tag, you can check the versioning again:
+
+.. code-block:: bash
+
+  $ versioningit .
+  0.1.0
+
+
 .. _ReadTheDocs: https://docs.readthedocs.io/en/stable/index.html
-.. _cookiecutter: https://cookiecutter.readthedocs.io/en/stable/
+.. _cookiecutter: https://cookiecutter.readthedocs.io/en/stable/
+.. _versioningit: https://versioningit.readthedocs.io/en/stable/index.html

{{cookiecutter.repo_name}}/MANIFEST.in

@@ -1,7 +1,6 @@
 include LICENSE
 include MANIFEST.in
 include AUTHORS.md CHANGELOG.md CODE_OF_CONDUCT.md README.md
-include versioneer.py
 
 graft {{cookiecutter.package_name}}
 global-exclude *.py[cod] __pycache__ *.so

{{cookiecutter.repo_name}}/pyproject.toml

@@ -1,7 +1,7 @@
 [build-system]
 requires = [
-  "setuptools >= 40.9.0",
-  "wheel",
+  "setuptools >=61.2",
+  "versioningit",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -42,6 +42,9 @@ doc = [
 # source = "https://github.com/{{cookiecutter.github_url}}"
 # documentation = "https://{{cookiecutter.repo_name}}.readthedocs.io"
 
+[tool.setuptools]
+py-modules = []
+
 [tool.pytest.ini_options]
 minversion = "6.0"
 testpaths = [
@@ -50,4 +53,17 @@ testpaths = [
 
 [tool.black]
 line-length = 80
-extend-exclude = "versioneer.py"
+
+[tool.versioningit]
+default-version = "1+unknown"
+
+[tool.versioningit.vcs]
+method = "git"
+# the below line expects tags to look like '1.0.2'.
+# if prefixing with a v, e.g. 'v1.0.2', change it to ["v*"]
+match = ["*"]
+
+[tool.versioningit.format]
+distance = "{base_version}+{distance}.{vcs}{rev}"
+dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
+distance-dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"

{{cookiecutter.repo_name}}/setup.cfg

@@ -5,8 +5,6 @@
 omit =
     # Omit the tests
     */tests/*
-    # Omit generated versioneer
-    {{cookiecutter.package_name}}/_version.py
 
 [coverage:report]
 exclude_also =
@@ -29,15 +27,6 @@ USE_TABS = False
 [flake8]
 # Flake8, PyFlakes, etc
 max-line-length = 80
-exclude = versioneer.py
-
-[versioneer]
-# Automatic version numbering scheme
-VCS = git
-style = pep440
-versionfile_source = {{cookiecutter.package_name}}/_version.py
-versionfile_build = {{cookiecutter.package_name}}/_version.py
-tag_prefix = ''
 
 [aliases]
 test = pytest