Skip to content

fix(version): always stage updated files #1214

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

Merged
merged 4 commits into from
Jun 12, 2025
Merged

fix(version): always stage updated files #1214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
62b1e0b
test(cmd-version): update version stamp test to verify changes are st…
codejedi365 Jun 7, 2025
365525a
feat(cmd-version): always stage version stamped files & changelogs ev…
codejedi365 Jun 7, 2025
8a2af44
docs(configuration-guide): add how-to guide for `uv` integration
codejedi365 Jun 8, 2025
dc16734
docs(cmd-version): improve command description & include common uses
codejedi365 Jun 8, 2025
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
77 changes: 63 additions & 14 deletions docs/api/commands.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,32 +96,81 @@ pipeline, while omitting this flag would allow the pipeline to continue to run.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Detect the semantically correct next version that should be applied to your
project.
project and release it.

By default:
By default (in order):

* Write this new version to the project metadata locations
specified in the configuration file
* Build the project using :ref:`config-build_command`, if specified
* Create a new commit with these locations and any other assets configured
to be included in a release
* Tag this commit according the configured format, with a tag that uniquely
identifies the version being released
* Push the new tag and commit to the remote for the repository
* Create a release (if supported) in the remote VCS for this tag
#. Write this new version to the project metadata locations
specified in the configuration file

#. Update the changelog file with the new version and any changes
introduced since the last release, using the configured changelog template

#. Build the project using :ref:`config-build_command`, if specified

#. Create a new commit with these locations and any other assets configured
to be included in a release

#. Tag this commit according the configured format, with a tag that uniquely
identifies the version being released

#. Push the new tag and commit to the remote for the repository

#. Create a release in the remote VCS for this tag (if supported)

All of these steps can be toggled on or off using the command line options
described below. Some of the steps rely on others, so some options may implicitly
disable others.

Changelog generation is done identically to the way it is done in :ref:`cmd-changelog`,
but this command additionally ensures the updated changelog is included in the release
commit that is made.

**Common Variations**

.. code-block:: bash

# Print the next version that will be applied
semantic-release version --print

# Print the next version that will be applied, including the tag prefix
semantic-release version --print-tag

# Print the last released version
semantic-release version --print-last-released

# Print the last released version, including the tag prefix
semantic-release version --print-last-released-tag

# Only stamp the next version in the project metadata locations
semantic-release version --no-changelog --skip-build --no-commit --no-tag

# Stamp the version, update the changelog, and run the build command, then stop
semantic-release version --no-commit --no-tag

# Make all local changes but do not publish them to the remote (changelog, build, commit & tag)
semantic-release version --no-push

# Don't ever create a changelog (but do everything else)
semantic-release version --no-changelog

# Don't create a release in the remote VCS (but do publish the commit and tag)
semantic-release version --no-vcs-release

# Do everything
semantic-release version


.. seealso::
- :ref:`Ultraviolet (uv) integration <config-guides-uv_integration>`
- :ref:`cmd-changelog`
- :ref:`changelog-templates`
- :ref:`config-tag_format`
- :ref:`config-assets`
- :ref:`config-version_toml`
- :ref:`config-version_variables`


.. _cmd-version-options:

Options:
Expand Down Expand Up @@ -362,9 +411,9 @@ Whether or not to push new commits and/or tags to the remote repository.
``--vcs-release/--no-vcs-release``
**********************************

Whether or not to create a "release" in the remote VCS service, if supported. Currently
releases in GitHub and Gitea remotes are supported. If releases aren't supported in a
remote VCS, this option will not cause a command failure, but will produce a warning.
Whether or not to create a "release" in the remote VCS service, if supported. If
releases aren't supported in a remote VCS, this option will not cause a command
failure, but will produce a warning.

**Default:** ``--no-vcs-release`` if ``--no-push`` is supplied (including where this is
implied by supplying only ``--no-commit``), otherwise ``--vcs-release``
Expand Down
14 changes: 14 additions & 0 deletions docs/configuration/configuration-guides/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
.. _config-guides:

Configuration Guides
====================

This section provides detailed guides on how to configure PSR for various use cases and
integrations. It is recommended to complete the
:ref:`Getting Started Guide <getting-started-guide>` first before diving into these
more specific configurations.

.. toctree::
:maxdepth: 1

UV Project Setup <uv_integration>
Loading
Loading