feat(print-version): add print-version command to output version

This new command can be integrated in the build process before the
effective release, ie. to rename some files with the version number.

Users may invoke `VERSION=$(semantic-release print-version)` to retrieve the
version that will be generated during the release before it really occurs.

docs/commands.rst

@@ -24,6 +24,19 @@ Figure out the new version number, update and commit it, and create a tag.
 
 This will not push anything to any remote. All changes are local.
 
+.. _cmd-print-version:
+
+``semantic-release print-version``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Print to standard output the new version number.
+
+If the option ``--current`` is used, it will display the current version number.
+
+It can be used to retrieve the next version number in a shell script during the build, before running the effective
+release, ie. to rename a distribution binary with the effective version::
+
+    VERSION=$(semantic-release print-version)
 
 .. _cmd-publish:
 

semantic_release/cli.py

@@ -416,7 +416,7 @@ def cmd_version(**kwargs):
         exit(1)
 
 
-@main.command(name="print-version", help=version.__doc__)
+@main.command(name="print-version", help=print_version.__doc__)
 @common_options
 @click.option('--current/--next', default=False, help="Choose to output next version (default) or current one.")
 def cmd_print_version(**kwargs):

tests/test_cli.py

@@ -1,7 +1,7 @@
 from click.testing import CliRunner
 
 import semantic_release
-from semantic_release.cli import changelog, main, publish, version
+from semantic_release.cli import changelog, main, publish, version, print_version
 from semantic_release.errors import GitError, ImproperConfigurationError
 
 from . import mock, pytest, reset_config, wrapped_config_get
@@ -190,6 +190,116 @@ def test_noop_mode(mocker):
     assert not mock_tag_new_version.called
 
 
+def test_cli_print_version(mocker, runner):
+    mock_print_version = mocker.patch("semantic_release.cli.print_version")
+    result = runner.invoke(main, ["print-version"])
+    mock_print_version.assert_called_once_with(
+        current=False,
+        force_level=None,
+        noop=False,
+        post=False,
+        retry=False,
+        define=(),
+    )
+    assert result.exit_code == 0
+
+
+def test_cli_print_version_force_major(mocker, runner):
+    mock_print_version = mocker.patch("semantic_release.cli.print_version")
+    result = runner.invoke(main, ["print-version", "--major"])
+    mock_print_version.assert_called_once_with(
+        current=False,
+        force_level="major",
+        noop=False,
+        post=False,
+        retry=False,
+        define=(),
+    )
+    assert result.exit_code == 0
+
+
+def test_cli_print_version_current(mocker, runner):
+    mock_print_version = mocker.patch("semantic_release.cli.print_version")
+    result = runner.invoke(main, ["print-version", "--current"])
+    mock_print_version.assert_called_once_with(
+        current=True,
+        force_level=None,
+        noop=False,
+        post=False,
+        retry=False,
+        define=(),
+    )
+    assert result.exit_code == 0
+
+
+def test_cli_print_version_next(mocker, runner):
+    mock_print_version = mocker.patch("semantic_release.cli.print_version")
+    result = runner.invoke(main, ["print-version", "--next"])
+    mock_print_version.assert_called_once_with(
+        current=False,
+        force_level=None,
+        noop=False,
+        post=False,
+        retry=False,
+        define=(),
+    )
+    assert result.exit_code == 0
+
+
+def test_print_version_no_change(mocker, runner, capsys):
+    mock_new_version = mocker.patch(
+        "semantic_release.cli.get_new_version", return_value="1.2.3"
+    )
+    mock_evaluate_bump = mocker.patch(
+        "semantic_release.cli.evaluate_version_bump", return_value=None
+    )
+    mock_current_version = mocker.patch(
+        "semantic_release.cli.get_current_version", return_value="1.2.3"
+    )
+
+    print_version()
+    outerr = capsys.readouterr()
+    assert outerr.out == ""
+    assert outerr.err == "No release will be made.\n"
+
+    mock_current_version.assert_called_once_with()
+    mock_evaluate_bump.assert_called_once_with("1.2.3", None)
+    mock_new_version.assert_called_once_with("1.2.3", None)
+
+
+def test_print_version_change(mocker, runner, capsys):
+    mock_current_version = mocker.patch(
+        "semantic_release.cli.get_current_version", return_value="1.2.3"
+    )
+    mock_evaluate_bump = mocker.patch(
+        "semantic_release.cli.evaluate_version_bump", return_value="minor"
+    )
+
+    print_version()
+    outerr = capsys.readouterr()
+    assert outerr.out == "1.3.0"
+    assert outerr.err == ""
+
+    mock_current_version.assert_called_once_with()
+    mock_evaluate_bump.assert_called_once_with("1.2.3", None)
+
+
+def test_print_version_force_major(mocker, runner, capsys):
+    mock_current_version = mocker.patch(
+        "semantic_release.cli.get_current_version", return_value="1.2.3"
+    )
+    mock_evaluate_bump = mocker.patch(
+        "semantic_release.cli.evaluate_version_bump", return_value="major"
+    )
+
+    print_version(force_level="major")
+    outerr = capsys.readouterr()
+    assert outerr.out == "2.0.0"
+    assert outerr.err == ""
+
+    mock_current_version.assert_called_once_with()
+    mock_evaluate_bump.assert_called_once_with("1.2.3", "major")
+
 def test_version_no_change(mocker, runner):
     mock_tag_new_version = mocker.patch("semantic_release.cli.tag_new_version")
     mock_commit_new_version = mocker.patch("semantic_release.cli.commit_new_version")