diff --git a/docs/configuration.rst b/docs/configuration.rst index f0eaeda4..e7c8a99d 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -43,7 +43,7 @@ Top level keys ``version`` The version of your project. - Python projects that provide the ``package`` key can have the version to be automatically determined from a ``__version__`` variable in the package's module. + Python projects that provide the ``package`` key, if left empty then the version will be automatically determined from the installed package's version metadata or a ``__version__`` variable in the package's module. If not provided or able to be determined, the version must be passed explicitly by the command line argument ``--version``. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 7138cd9e..258a1323 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -48,19 +48,27 @@ Create this folder:: The ``.gitignore`` will remain and keep Git from not tracking the directory. -Detecting Dates & Versions --------------------------- +Detecting Version +----------------- -``towncrier`` needs to know what version your project is, and there are two ways you can give it: +``towncrier`` needs to know what version your project is when generating news files. +These are the ways you can provide it, in order of precedence (with the first taking precedence over the second, and so on): -- For Python 2/3-compatible projects, a ``__version__`` in the top level package. - This can be either a string literal, a tuple, or an `Incremental `_ version. -- Manually passing ``--version=`` when interacting with ``towncrier``. +1. Manually pass ``--version=`` when interacting with ``towncrier``. +2. Set a value for the ``version`` option in your configuration file. +3. For Python projects with a ``package`` key in the configuration file: -As an example, if your package doesn't have a ``__version__``, you can manually specify it when calling ``towncrier`` on the command line with the ``--version`` flag:: + - install the package to use its metadata version information + - add a ``__version__`` in the top level package that is either a string literal, a tuple, or an `Incremental `_ version + +As an example, you can manually specify the version when calling ``towncrier`` on the command line with the ``--version`` flag:: $ towncrier build --version=1.2.3post4 + +Setting Date +------------ + ``towncrier`` will also include the current date (in ``YYYY-MM-DD`` format) when generating news files. You can change this with the ``--date`` flag:: diff --git a/src/towncrier/newsfragments/432.doc.rst b/src/towncrier/newsfragments/432.doc.rst new file mode 100644 index 00000000..92e5247f --- /dev/null +++ b/src/towncrier/newsfragments/432.doc.rst @@ -0,0 +1 @@ +Clarify version discovery behavior. diff --git a/src/towncrier/newsfragments/602.doc.rst b/src/towncrier/newsfragments/602.doc.rst new file mode 100644 index 00000000..92e5247f --- /dev/null +++ b/src/towncrier/newsfragments/602.doc.rst @@ -0,0 +1 @@ +Clarify version discovery behavior.