From 2fac075bdec2cc578fb62e9d8433885aba8bcd73 Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Thu, 23 May 2024 15:25:57 +1200 Subject: [PATCH 1/5] Update docs around versions --- docs/configuration.rst | 2 +- docs/tutorial.rst | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) 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..eeb8f211 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -51,13 +51,15 @@ The ``.gitignore`` will remain and keep Git from not tracking the directory. Detecting Dates & Versions -------------------------- -``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. These are the ways you can provide it (and their order of precedence): -- 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 ``version`` key in your configuration file. +3. For Python projects with a ``package`` key in the configuration file: + - 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, if your package doesn't have a ``__version__``, you can manually specify it when calling ``towncrier`` on the command line with the ``--version`` flag:: +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 From 7895f0376ac9345825251cf7064d0a81b8e7a12f Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Thu, 23 May 2024 15:30:20 +1200 Subject: [PATCH 2/5] Add news fragments --- src/towncrier/newsfragments/432.doc.rst | 1 + src/towncrier/newsfragments/602.doc.rst | 1 + 2 files changed, 2 insertions(+) create mode 100644 src/towncrier/newsfragments/432.doc.rst create mode 100644 src/towncrier/newsfragments/602.doc.rst 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. From 33165a07b0f22b2e2cdf7d7f7f7836894c1e2961 Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Thu, 23 May 2024 15:34:09 +1200 Subject: [PATCH 3/5] rst bullet point fix --- docs/tutorial.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index eeb8f211..cf56a0b0 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -56,6 +56,7 @@ Detecting Dates & Versions 1. Manually pass ``--version=`` when interacting with ``towncrier``. 2. Set a ``version`` key in your configuration file. 3. For Python projects with a ``package`` key in the configuration file: + - 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 From fe77ea277c113b3706cf46c20f96dd6338b6cc6b Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Fri, 24 May 2024 11:04:06 +1200 Subject: [PATCH 4/5] Requested doc changes --- docs/tutorial.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index cf56a0b0..f72afcbe 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -48,13 +48,14 @@ 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. These are the ways you can provide it (and their order of precedence): +``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): 1. Manually pass ``--version=`` when interacting with ``towncrier``. -2. Set a ``version`` key in your configuration file. +2. Set a value for the ``version`` option in your configuration file. 3. For Python projects with a ``package`` key in the configuration file: - install the package to use its metadata version information @@ -64,6 +65,10 @@ As an example, you can manually specify the version when calling ``towncrier`` o $ 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:: From d7c8c39a5cf3cf7b4ae00fde4b5f4b604099f090 Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Fri, 24 May 2024 11:05:08 +1200 Subject: [PATCH 5/5] Comma --- docs/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index f72afcbe..258a1323 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -52,7 +52,7 @@ Detecting Version ----------------- ``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): +These are the ways you can provide it, in order of precedence (with the first taking precedence over the second, and so on): 1. Manually pass ``--version=`` when interacting with ``towncrier``. 2. Set a value for the ``version`` option in your configuration file.