Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs around version discovery #602

Merged
merged 5 commits into from
May 23, 2024
Merged

Update docs around version discovery #602

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2fac075
Update docs around versions
SmileyChris May 23, 2024
7895f03
Add news fragments
SmileyChris May 23, 2024
33165a0
rst bullet point fix
SmileyChris May 23, 2024
fe77ea2
Requested doc changes
SmileyChris May 23, 2024
d7c8c39
Comma
SmileyChris May 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
13 changes: 8 additions & 5 deletions docs/tutorial.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,16 @@ The ``.gitignore`` will remain and keep Git from not tracking the directory.
Detecting Dates & Versions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it's best to have a separate section for version and date.

Most of the info from this section is about version.

A separate section should make it easier to jump to the information aboute date.

and I think that it only detects the current version, so not plural.

Suggested change
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. These are the ways you can provide it (and their order of precedence):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's best to use Semantic newlines for documentation content.

Maybe also update this page
https://towncrier.readthedocs.io/en/latest/contributing.html

I guess that not every operaition needs the version.
I don't expect to requiere the version for a create command.

It's not 100% clear what's the order of precendece.

Suggested change
``towncrier`` needs to know what version your project is. These are the ways you can provide it (and their order of precedence):
Most ``towncrier`` commands, like `build` or `check`, needs to know what version your project is.
These are the ways you can provide it and their order of precedence.
A lower precedence number will overwrite any other method with a higher number:


- 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 <https://github.com/twisted/incremental>`_ version.
- Manually passing ``--version=<myversionhere>`` when interacting with ``towncrier``.
1. Manually pass ``--version=<myversionhere>`` when interacting with ``towncrier``.
2. Set a ``version`` key in your configuration file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:

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 <https://github.com/twisted/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

Expand Down
1 change: 1 addition & 0 deletions src/towncrier/newsfragments/432.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Clarify version discovery behavior.
1 change: 1 addition & 0 deletions src/towncrier/newsfragments/602.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Clarify version discovery behavior.
Loading