From 19add16dcfdfdb812efafe2d492a933d0856df1d Mon Sep 17 00:00:00 2001 From: codejedi365 Date: Sun, 12 May 2024 20:03:49 -0400 Subject: [PATCH] docs(configuration): clarify TOC & alphabetize configuration descriptions --- docs/configuration.rst | 786 ++++++++++++++++++++++------------------- 1 file changed, 421 insertions(+), 365 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index 406758d6e..2591c62ce 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -97,7 +97,7 @@ In this structure: .. _config-root: -Settings ``semantic_release`` +``semantic_release`` settings ----------------------------- The following sections outline all the definitions and descriptions of each supported @@ -117,11 +117,37 @@ sure to use the correct root key dependending on the configuration format you ar ---- -.. _config-assets: +.. _config-allow_zero_version: -``assets (List[str])`` +``allow_zero_version`` """""""""""""""""""""" +**Type:** ``bool`` + +This flag controls whether or not Python Semantic Release will use version +numbers aligning with the ``0.x.x`` pattern. + +If set to ``true`` and starting at ``0.0.0``, a minor bump would set the +next version as ``0.1.0`` whereas a patch bump would set the next version as +``0.0.1``. A breaking change (ie. major bump) would set the next version as +``1.0.0`` unless the :ref:`config-major_on_zero` is set to ``false``. + +If set to ``false``, Python Semantic Release will consider the first possible +version to be ``1.0.0``, regardless of patch, minor, or major change level. +Additionally, when ``allow_zero_version`` is set to ``false``, +the :ref:`config-major_on_zero` setting is ignored. + +**Default:** ``true`` + +---- + +.. _config-assets: + +``assets`` +"""""""""" + +**Type:** ``list[str]`` + One or more paths to additional assets that should committed to the remote repository in addition to any files modified by writing the new version. @@ -216,321 +242,257 @@ FORMAT Description ---- -.. _config-commit_author: +.. _config-changelog: -``commit_author (str)`` -""""""""""""""""""""""" -Author used in commits in the format ``name ``. +``changelog`` +""""""""""""" + +This section outlines the configuration options available that modify changelog generation. .. note:: - If you are using the built-in GitHub Action, the default value is set to - ``github-actions ``. You can modify this with the - ``git_committer_name`` and ``git_committer_name`` inputs. + **pyproject.toml:** ``[tool.semantic_release.changelog]`` -.. seealso:: - - :ref:`github-actions` + **releaserc.toml:** ``[semantic_release.changelog]`` -**Default:** ``semantic-release `` + **releaserc.json:** ``{ "semantic_release": { "changelog": {} } }`` ---- -.. _config-commit_message: +.. _config-changelog-changelog_file: -``commit_message (str)`` -"""""""""""""""""""""""" +``changelog_file`` +****************** -Commit message to use when making release commits. The message can use ``{version}`` -as a format key, in which case the version being released will be formatted into -the message. +**Type:** ``str`` -If at some point in your project's lifetime you change this, you may wish to consider, -adding the old message pattern(s) to :ref:`exclude_commit_patterns `. +Specify the name of the changelog file (after template rendering has taken place). -**Default:** ``"{version}\n\nAutomatically generated by python-semantic-release"`` +**Default:** ``"CHANGELOG.md"`` ---- -.. _config-commit_parser: +.. _config-changelog-environment: -``commit_parser (str)`` -""""""""""""""""""""""" +``environment`` +*************** -Specify which commit parser Python Semantic Release should use to parse the commits -within the Git repository. +.. note:: + This section of the configuration contains options which customize the template + environment used to render templates such as the changelog. Most options are + passed directly to the `jinja2.Environment`_ constructor, and further + documentation one these parameters can be found there. -Built-in parsers: - * ``angular`` - :ref:`AngularCommitParser ` - * ``emoji`` - :ref:`EmojiCommitParser ` - * ``scipy`` - :ref:`ScipyCommitParser ` - * ``tag`` - :ref:`TagCommitParser ` +.. _`jinja2.Environment`: https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment -You can set any of the built-in parsers by their keyword but you can also specify -your own commit parser in ``module:attr`` form. +.. note:: + **pyproject.toml:** ``[tool.semantic_release.changelog.environment]`` -For more information see :ref:`commit-parsing`. + **releaserc.toml:** ``[semantic_release.changelog.environment]`` -**Default:** ``"angular"`` + **releaserc.json:** ``{ "semantic_release": { "changelog": { "environment": {} } } }`` ---- -.. _config-commit_parser_options: - -``commit_parser_options (Dict[str, Any])`` -"""""""""""""""""""""""""""""""""""""""""" - -These options are passed directly to the ``parser_options`` method of -:ref:`the commit parser `, without validation -or transformation. +.. _config-changelog-environment-autoescape: -For more information, see :ref:`commit-parsing-parser-options`. +``autoescape`` +'''''''''''''' -The default value for this setting depends on what you specify as -:ref:`commit_parser `. The table below outlines -the expections from ``commit_parser`` value to default options value. +**Type:** ``Union[str, bool]`` -================== == ================================= -``commit_parser`` Default ``commit_parser_options`` -================== == ================================= -``"angular"`` -> .. code-block:: toml +If this setting is a string, it should be given in ``module:attr`` form; Python +Semantic Release will attempt to dynamically import this string, which should +represent a path to a suitable callable that satisfies the following: - [semantic_release.commit_parser_options] - allowed_types = [ - "build", "chore", "ci", "docs", "feat", "fix", - "perf", "style", "refactor", "test" - ] - minor_types = ["feat"] - patch_types = ["fix", "perf"] + As of Jinja 2.4 this can also be a callable that is passed the template name + and has to return ``True`` or ``False`` depending on autoescape should be + enabled by default. -``"emoji"`` -> .. code-block:: toml +The result of this dynamic import is passed directly to the `jinja2.Environment`_ +constructor. - [semantic_release.commit_parser_options] - major_tags = [":boom:"] - minor_tags = [ - ":sparkles:", ":children_crossing:", ":lipstick:", - ":iphone:", ":egg:", ":chart_with_upwards_trend:" - ] - patch_tags = [ - ":ambulance:", ":lock:", ":bug:", ":zap:", ":goal_net:", - ":alien:", ":wheelchair:", ":speech_balloon:", ":mag:", - ":apple:", ":penguin:", ":checkered_flag:", ":robot:", - ":green_apple:" - ] +If this setting is a boolean, it is passed directly to the `jinja2.Environment`_ +constructor. -``"scipy"`` -> .. code-block:: toml +**Default:** ``true`` - [semantic_release.commit_parser_options] - allowed_tags = [ - "API", "DEP", "ENH", "REV", "BUG", "MAINT", "BENCH", - "BLD", "DEV", "DOC", "STY", "TST", "REL", "FEAT", "TEST", - ] - major_tags = ["API",] - minor_tags = ["DEP", "DEV", "ENH", "REV", "FEAT"] - patch_tags = ["BLD", "BUG", "MAINT"] +---- -``"tag"`` -> .. code-block:: toml +.. _config-changelog-environment-block_start_string: - [semantic_release.commit_parser_options] - minor_tag = ":sparkles:" - patch_tag = ":nut_and_bolt:" +``block_start_string`` +'''''''''''''''''''''' -``"module:class"`` -> ``**module:class.parser_options()`` -================== == ================================= +**Type:** ``str`` -**Default:** ``ParserOptions { ... }``, where ``...`` depends on -:ref:`commit_parser ` as indicated above. +This setting is passed directly to the `jinja2.Environment`_ constructor. +**Default:** ``"{%"`` ---- -.. _config-logging_use_named_masks: +.. _config-changelog-environment-block_end_string: -``logging_use_named_masks (bool)`` -"""""""""""""""""""""""""""""""""" +``block_end_string`` +'''''''''''''''''''' -Whether or not to replace secrets identified in logging messages with named masks -identifying which secrets were replaced, or use a generic string to mask them. +**Type:** ``str`` -**Default:** ``false`` +This setting is passed directly to the `jinja2.Environment`_ constructor. + +**Default:** ``"%}"`` ---- -.. _config-allow_zero_version: +.. _config-changelog-environment-comment_start_string: -``allow_zero_version`` -"""""""""""""""""""""" +``comment_start_string`` +'''''''''''''''''''''''' -**Type:** ``bool`` +**Type:** ``str`` -This flag controls whether or not Python Semantic Release will use version -numbers aligning with the ``0.x.x`` pattern. +This setting is passed directly to the `jinja2.Environment`_ constructor. -If set to ``true`` and starting at ``0.0.0``, a minor bump would set the -next version as ``0.1.0`` whereas a patch bump would set the next version as -``0.0.1``. A breaking change (ie. major bump) would set the next version as -``1.0.0`` unless the :ref:`config-major_on_zero` is set to ``false``. +**Default:** ``{#`` -If set to ``false``, Python Semantic Release will consider the first possible -version to be ``1.0.0``, regardless of patch, minor, or major change level. -Additionally, when ``allow_zero_version`` is set to ``false``, -the :ref:`config-major_on_zero` setting is ignored. +---- -**Default:** ``true`` +.. _config-changelog-environment-comment_end_string: + +``comment_end_string`` +'''''''''''''''''''''' + +**Type:** ``str`` + +This setting is passed directly to the `jinja2.Environment`_ constructor. + +**Default:** ``"#}"`` ---- -.. _config-major_on_zero: +.. _config-changelog-environment-extensions: -``major_on_zero`` -""""""""""""""""" +``extensions`` +'''''''''''''' -**Type:** ``bool`` +**Type:** ``list[str]`` -This flag controls whether or not Python Semantic Release will increment the major -version upon a breaking change when the version matches ``0.y.z``. This value is -set to ``true`` by default, where breaking changes will increment the ``0`` major -version to ``1.0.0`` like normally expected. +This setting is passed directly to the `jinja2.Environment`_ constructor. -If set to ``false``, major (breaking) releases will increment the minor digit of the -version while the major version is ``0``, instead of the major digit. This allows for -continued breaking changes to be made while the major version remains ``0``. +**Default:** ``[]`` -From the `Semantic Versioning Specification`_: +---- - Major version zero (0.y.z) is for initial development. Anything MAY change at - any time. The public API SHOULD NOT be considered stable. +.. _config-changelog-environment-keep_trailing_newline: -.. _Semantic Versioning Specification: https://semver.org/spec/v2.0.0.html#spec-item-4 +``keep_trailing_newline`` +''''''''''''''''''''''''' -When you are ready to release a stable version, set ``major_on_zero`` to ``true`` and -run Python Semantic Release again. This will increment the major version to ``1.0.0``. +**Type:** ``bool`` -When :ref:`config-allow_zero_version` is set to ``false``, this setting is ignored. +This setting is passed directly to the `jinja2.Environment`_ constructor. -**Default:** ``true`` +**Default:** ``false`` ---- -.. _config-tag_format: +.. _config-changelog-environment-line_comment_prefix: -``tag_format (str)`` -"""""""""""""""""""" +``line_comment_prefix`` +''''''''''''''''''''''' -Specify the format to be used for the Git tag that will be added to the repo during -a release invoked via :ref:`cmd-version`. The format string is a regular expression, -which also must include the format keys below, otherwise an exception will be thrown. -It *may* include any of the optional format keys, in which case the contents -described will be formatted into the specified location in the Git tag that is created. +**Type:** ``Optional[str]`` -For example, ``"(dev|stg|prod)-v{version}"`` is a valid ``tag_format`` matching tags such -as: +This setting is passed directly to the `jinja2.Environment`_ constructor. -- ``dev-v1.2.3`` -- ``stg-v0.1.0-rc.1`` -- ``prod-v2.0.0+20230701`` +**Default:** ``None`` (not specified) -This format will also be used for parsing tags already present in the repository into -semantic versions; therefore if the tag format changes at some point in the -repository's history, historic versions that no longer match this pattern will not be -considered as versions. +---- -================ ========= ======== -Format Key Mandatory Contents -================ ========= ======== -``{version}`` Yes The new semantic version number, for example ``1.2.3``, or - ``2.1.0-alpha.1+build.1234`` -================ ========= ======== +.. _config-changelog-environment-line_statement_prefix: -Tags which do not match this format will not be considered as versions of your project. +``line_statement_prefix`` +''''''''''''''''''''''''' -**Default:** ``"v{version}"`` +**Type:** ``Optional[str]`` ----- +This setting is passed directly to the `jinja2.Environment`_ constructor. -.. _config-version_variables: +**Default:** ``None`` (not specified) -``version_variables (List[str])`` -""""""""""""""""""""""""""""""""" +---- -Each entry represents a location where the version is stored in the source code, -specified in ``file:variable`` format. For example: +.. _config-changelog-environment-lstrip_blocks: -.. code-block:: toml +``lstrip_blocks`` +''''''''''''''''' - [semantic_release] - version_variables = [ - "semantic_release/__init__.py:__version__", - "docs/conf.py:version", - ] +**Type:** ``bool`` -**Default:** ``[]`` +This setting is passed directly to the `jinja2.Environment`_ constructor. ----- +**Default:** ``false`` -.. _config-version_toml: +---- -``version_toml (List[str])`` -"""""""""""""""""""""""""""" +.. _config-changelog-environment-newline_sequence: -Similar to :ref:`config-version_variables`, but allows the version number to be -identified safely in a toml file like ``pyproject.toml``, with each entry using -dotted notation to indicate the key for which the value represents the version: +``newline_sequence`` +'''''''''''''''''''' -.. code-block:: toml +**Type:** ``Literal["\n", "\r", "\r\n"]`` - [semantic_release] - version_toml = [ - "pyproject.toml:tool.poetry.version", - ] +This setting is passed directly to the `jinja2.Environment`_ constructor. -**Default:** ``[]`` +**Default:** ``"\n"`` ---- -.. _config-changelog: +.. _config-changelog-environment-trim_blocks: -``changelog`` -""""""""""""" +``trim_blocks`` +''''''''''''''' -This section outlines the configuration options available that modify changelog generation. - -.. note:: - **pyproject.toml:** ``[tool.semantic_release.changelog]`` +**Type:** ``bool`` - **releaserc.toml:** ``[semantic_release.changelog]`` +This setting is passed directly to the `jinja2.Environment`_ constructor. - **releaserc.json:** ``{ "semantic_release": { "changelog": {} } }`` +**Default:** ``false`` ---- -.. _config-changelog-template_dir: +.. _config-changelog-environment-variable_start_string: -``template_dir (str)`` -********************** +``variable_start_string`` +''''''''''''''''''''''''' -If given, specifies a directory of templates that will be rendered during creation -of the changelog. If not given, the default changelog template will be used. +**Type:** ``str`` -This option is discussed in more detail at :ref:`changelog-templates` +This setting is passed directly to the `jinja2.Environment`_ constructor. -**Default:** ``"templates"`` +**Default:** ``"{{"`` ---- -.. _config-changelog-changelog_file: +.. _config-changelog-environment-variable_end_string: -``changelog_file (str)`` -************************ +``variable_end_string`` +''''''''''''''''''''''' -Specify the name of the changelog file (after template rendering has taken place). +**Type:** ``str`` -**Default:** ``"CHANGELOG.md"`` +This setting is passed directly to the `jinja2.Environment`_ constructor. + +**Default:** ``"}}"`` ---- .. _config-changelog-exclude_commit_patterns: -``exclude_commit_patterns (List[str])`` -*************************************** +``exclude_commit_patterns`` +*************************** + +**Type:** ``list[str]`` Any patterns specified here will be excluded from the commits which are available to your changelog. This allows, for example, automated commits to be removed if desired. @@ -544,189 +506,243 @@ The patterns in this list are treated as regular expressions. ---- -.. _config-changelog-environment: - -``environment`` -*************** +.. _config-changelog-template_dir: -.. note:: - This section of the configuration contains options which customize the template - environment used to render templates such as the changelog. Most options are - passed directly to the `jinja2.Environment`_ constructor, and further - documentation one these parameters can be found there. +``template_dir`` +**************** -.. _`jinja2.Environment`: https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment +**Type:** ``str`` -.. note:: - **pyproject.toml:** ``[tool.semantic_release.changelog.environment]`` +If given, specifies a directory of templates that will be rendered during creation +of the changelog. If not given, the default changelog template will be used. - **releaserc.toml:** ``[semantic_release.changelog.environment]`` +This option is discussed in more detail at :ref:`changelog-templates` - **releaserc.json:** ``{ "semantic_release": { "changelog": { "environment": {} } } }`` +**Default:** ``"templates"`` ---- -.. _config-changelog-environment-block_start_string: +.. _config-commit_author: -``block_start_string (str)`` -'''''''''''''''''''''''''''' +``commit_author`` +""""""""""""""""" -This setting is passed directly to the `jinja2.Environment`_ constructor. +**Type:** ``str`` -**Default:** ``"{%"`` +Author used in commits in the format ``name ``. + +.. note:: + If you are using the built-in GitHub Action, the default value is set to + ``github-actions ``. You can modify this with the + ``git_committer_name`` and ``git_committer_name`` inputs. + +.. seealso:: + - :ref:`github-actions` + +**Default:** ``semantic-release `` ---- -.. _config-changelog-environment-block_end_string: +.. _config-commit_message: -``block_end_string (str)`` -'''''''''''''''''''''''''' +``commit_message`` +"""""""""""""""""" -This setting is passed directly to the `jinja2.Environment`_ constructor. +**Type:** ``str`` -**Default:** ``"%}"`` +Commit message to use when making release commits. The message can use ``{version}`` +as a format key, in which case the version being released will be formatted into +the message. + +If at some point in your project's lifetime you change this, you may wish to consider, +adding the old message pattern(s) to :ref:`exclude_commit_patterns `. + +**Default:** ``"{version}\n\nAutomatically generated by python-semantic-release"`` ---- -.. _config-changelog-environment-variable_start_string: +.. _config-commit_parser: -``variable_start_string (str)`` -''''''''''''''''''''''''''''''' +``commit_parser`` +""""""""""""""""" -This setting is passed directly to the `jinja2.Environment`_ constructor. +**Type:** ``str`` -**Default:** ``"{{"`` +Specify which commit parser Python Semantic Release should use to parse the commits +within the Git repository. + +Built-in parsers: + * ``angular`` - :ref:`AngularCommitParser ` + * ``emoji`` - :ref:`EmojiCommitParser ` + * ``scipy`` - :ref:`ScipyCommitParser ` + * ``tag`` - :ref:`TagCommitParser ` + +You can set any of the built-in parsers by their keyword but you can also specify +your own commit parser in ``module:attr`` form. + +For more information see :ref:`commit-parsing`. + +**Default:** ``"angular"`` ---- -.. _config-changelog-environment-variable_end_string: +.. _config-commit_parser_options: -``variable_end_string (str)`` -''''''''''''''''''''''''''''' +``commit_parser_options`` +""""""""""""""""""""""""" -This setting is passed directly to the `jinja2.Environment`_ constructor. +**Type:** ``dict[str, Any]`` -**Default:** ``"}}"`` +These options are passed directly to the ``parser_options`` method of +:ref:`the commit parser `, without validation +or transformation. ----- +For more information, see :ref:`commit-parsing-parser-options`. -.. _config-changelog-environment-comment_start_string: +The default value for this setting depends on what you specify as +:ref:`commit_parser `. The table below outlines +the expections from ``commit_parser`` value to default options value. -``comment_start_string (str)`` -'''''''''''''''''''''''''''''' +================== == ================================= +``commit_parser`` Default ``commit_parser_options`` +================== == ================================= +``"angular"`` -> .. code-block:: toml -This setting is passed directly to the `jinja2.Environment`_ constructor. + [semantic_release.commit_parser_options] + allowed_types = [ + "build", "chore", "ci", "docs", "feat", "fix", + "perf", "style", "refactor", "test" + ] + minor_types = ["feat"] + patch_types = ["fix", "perf"] + +``"emoji"`` -> .. code-block:: toml + + [semantic_release.commit_parser_options] + major_tags = [":boom:"] + minor_tags = [ + ":sparkles:", ":children_crossing:", ":lipstick:", + ":iphone:", ":egg:", ":chart_with_upwards_trend:" + ] + patch_tags = [ + ":ambulance:", ":lock:", ":bug:", ":zap:", ":goal_net:", + ":alien:", ":wheelchair:", ":speech_balloon:", ":mag:", + ":apple:", ":penguin:", ":checkered_flag:", ":robot:", + ":green_apple:" + ] -**Default:** ``{#`` +``"scipy"`` -> .. code-block:: toml ----- + [semantic_release.commit_parser_options] + allowed_tags = [ + "API", "DEP", "ENH", "REV", "BUG", "MAINT", "BENCH", + "BLD", "DEV", "DOC", "STY", "TST", "REL", "FEAT", "TEST", + ] + major_tags = ["API",] + minor_tags = ["DEP", "DEV", "ENH", "REV", "FEAT"] + patch_tags = ["BLD", "BUG", "MAINT"] -.. _config-changelog-environment-comment_end_string: +``"tag"`` -> .. code-block:: toml -``comment_end_string (str)`` -'''''''''''''''''''''''''''' + [semantic_release.commit_parser_options] + minor_tag = ":sparkles:" + patch_tag = ":nut_and_bolt:" -This setting is passed directly to the `jinja2.Environment`_ constructor. +``"module:class"`` -> ``**module:class.parser_options()`` +================== == ================================= -**Default:** ``"#}"`` +**Default:** ``ParserOptions { ... }``, where ``...`` depends on +:ref:`config-commit_parser` as indicated above. ---- -.. _config-changelog-environment-line_statement_prefix: - -``line_statement_prefix (Optional[str])`` -''''''''''''''''''''''''''''''''''''''''' - -This setting is passed directly to the `jinja2.Environment`_ constructor. - -**Default:** ``None`` (not specified) - ----- +.. _config-logging_use_named_masks: -.. _config-changelog-environment-line_comment_prefix: +``logging_use_named_masks`` +""""""""""""""""""""""""""" -``line_comment_prefix (Optional[str])`` -''''''''''''''''''''''''''''''''''''''' +**Type:** ``bool`` -This setting is passed directly to the `jinja2.Environment`_ constructor. +Whether or not to replace secrets identified in logging messages with named masks +identifying which secrets were replaced, or use a generic string to mask them. -**Default:** ``None`` (not specified) +**Default:** ``false`` ---- -.. _config-changelog-environment-trim_blocks: - -``trim_blocks (bool)`` -'''''''''''''''''''''' +.. _config-major_on_zero: -This setting is passed directly to the `jinja2.Environment`_ constructor. +``major_on_zero`` +""""""""""""""""" -**Default:** ``false`` +**Type:** ``bool`` ----- +This flag controls whether or not Python Semantic Release will increment the major +version upon a breaking change when the version matches ``0.y.z``. This value is +set to ``true`` by default, where breaking changes will increment the ``0`` major +version to ``1.0.0`` like normally expected. -.. _config-changelog-environment-lstrip_blocks: +If set to ``false``, major (breaking) releases will increment the minor digit of the +version while the major version is ``0``, instead of the major digit. This allows for +continued breaking changes to be made while the major version remains ``0``. -``lstrip_blocks (bool)`` -'''''''''''''''''''''''' +From the `Semantic Versioning Specification`_: -This setting is passed directly to the `jinja2.Environment`_ constructor. + Major version zero (0.y.z) is for initial development. Anything MAY change at + any time. The public API SHOULD NOT be considered stable. -**Default:** ``false`` +.. _Semantic Versioning Specification: https://semver.org/spec/v2.0.0.html#spec-item-4 ----- +When you are ready to release a stable version, set ``major_on_zero`` to ``true`` and +run Python Semantic Release again. This will increment the major version to ``1.0.0``. -.. _config-changelog-environment-newline_sequence: +When :ref:`config-allow_zero_version` is set to ``false``, this setting is ignored. -``newline_sequence (Literal["\n", "\r", "\r\n"])`` -'''''''''''''''''''''''''''''''''''''''''''''''''' +**Default:** ``true`` -This setting is passed directly to the `jinja2.Environment`_ constructor. +---- -**Default:** ``"\n"`` +.. _config-publish: ----- +``publish`` +""""""""""" -.. _config-changelog-environment-keep_trailing_newline: +This section defines configuration options that modify :ref:`cmd-publish`. -``keep_trailing_newline (bool)`` -'''''''''''''''''''''''''''''''' +.. note:: + **pyproject.toml:** ``[tool.semantic_release.publish]`` -This setting is passed directly to the `jinja2.Environment`_ constructor. + **releaserc.toml:** ``[semantic_release.publish]`` -**Default:** ``false`` + **releaserc.json:** ``{ "semantic_release": { "publish": {} } }`` ---- -.. _config-changelog-environment-extensions: - -``extensions (List[str])`` -'''''''''''''''''''''''''' +.. _config-publish-dist_glob_patterns: -This setting is passed directly to the `jinja2.Environment`_ constructor. +``dist_glob_patterns`` +********************** -**Default:** ``[]`` +**Type:** ``list[str]`` ----- +Upload any files matching any of these globs to your VCS release. Each item in this +list should be a string containing a Unix-style glob pattern. -.. _config-changelog-environment-autoescape: +**Default:** ``["dist/*"]`` -``autoescape (Union[str, bool])`` -''''''''''''''''''''''''''''''''' +---- -If this setting is a string, it should be given in ``module:attr`` form; Python -Semantic Release will attempt to dynamically import this string, which should -represent a path to a suitable callable that satisfies the following: +.. _config-publish-upload_to_vcs_release: - As of Jinja 2.4 this can also be a callable that is passed the template name - and has to return ``True`` or ``False`` depending on autoescape should be - enabled by default. +``upload_to_vcs_release`` +************************* -The result of this dynamic import is passed directly to the `jinja2.Environment`_ -constructor. +**Type:** ``bool`` -If this setting is a boolean, it is passed directly to the `jinja2.Environment`_ -constructor. +If set to ``true``, upload any artifacts matched by the +:ref:`dist_glob_patterns ` to the release created +in the remote VCS corresponding to the latest tag. Artifacts are only uploaded if +release artifact uploads are supported by the :ref:`VCS type `. **Default:** ``true`` @@ -873,41 +889,6 @@ Name of the remote to push to using ``git push -u $name `` ---- -.. _config-remote-url: - -``url`` -******* - -**Type:** ``Optional[str | Dict['env', str]]`` - -An override setting used to specify the remote upstream location of ``git push``. - -**Not commonly used!** This is used to override the derived upstream location when -the desired push location is different than the location the repository was cloned -from. - -This setting will override the upstream location url that would normally be derived -from the :ref:`remote.name ` location of your git repository. - -**Default:** ``None`` - ----- - -.. _config-remote-type: - -``type`` -******** - -**Type:** ``Literal["bitbucket", "gitea", "github", "gitlab"]`` - -The type of the remote VCS. Currently, Python Semantic Release supports ``"github"``, -``"gitlab"``, ``"gitea"`` and ``"bitbucket"``. Not all functionality is available with all -remote types, but we welcome pull requests to help improve this! - -**Default:** ``"github"`` - ----- - .. _config-remote-token: ``token`` @@ -952,42 +933,117 @@ default token value will be for each remote type. ---- -.. _config-publish: +.. _config-remote-type: -``publish`` -""""""""""" +``type`` +******** -This section defines configuration options that modify :ref:`cmd-publish`. +**Type:** ``Literal["bitbucket", "gitea", "github", "gitlab"]`` -.. note:: - **pyproject.toml:** ``[tool.semantic_release.publish]`` +The type of the remote VCS. Currently, Python Semantic Release supports ``"github"``, +``"gitlab"``, ``"gitea"`` and ``"bitbucket"``. Not all functionality is available with all +remote types, but we welcome pull requests to help improve this! - **releaserc.toml:** ``[semantic_release.publish]`` +**Default:** ``"github"`` - **releaserc.json:** ``{ "semantic_release": { "publish": {} } }`` +---- + +.. _config-remote-url: + +``url`` +******* + +**Type:** ``Optional[str | Dict['env', str]]`` + +An override setting used to specify the remote upstream location of ``git push``. + +**Not commonly used!** This is used to override the derived upstream location when +the desired push location is different than the location the repository was cloned +from. + +This setting will override the upstream location url that would normally be derived +from the :ref:`remote.name ` location of your git repository. + +**Default:** ``None`` ---- -.. _config-publish-dist_glob_patterns: +.. _config-tag_format: -``dist_glob_patterns (List[str])`` -********************************** +``tag_format`` +"""""""""""""" -Upload any files matching any of these globs to your VCS release. Each item in this -list should be a string containing a Unix-style glob pattern. +**Type:** ``str`` -**Default:** ``["dist/*"]`` +Specify the format to be used for the Git tag that will be added to the repo during +a release invoked via :ref:`cmd-version`. The format string is a regular expression, +which also must include the format keys below, otherwise an exception will be thrown. +It *may* include any of the optional format keys, in which case the contents +described will be formatted into the specified location in the Git tag that is created. + +For example, ``"(dev|stg|prod)-v{version}"`` is a valid ``tag_format`` matching tags such +as: + +- ``dev-v1.2.3`` +- ``stg-v0.1.0-rc.1`` +- ``prod-v2.0.0+20230701`` + +This format will also be used for parsing tags already present in the repository into +semantic versions; therefore if the tag format changes at some point in the +repository's history, historic versions that no longer match this pattern will not be +considered as versions. + +================ ========= ========================================================== +Format Key Mandatory Contents +================ ========= ========================================================== +``{version}`` Yes The new semantic version number, for example ``1.2.3``, or + ``2.1.0-alpha.1+build.1234`` +================ ========= ========================================================== + +Tags which do not match this format will not be considered as versions of your project. + +**Default:** ``"v{version}"`` ---- -.. _config-publish-upload_to_vcs_release: +.. _config-version_toml: -``upload_to_vcs_release (bool)`` -******************************** +``version_toml`` +"""""""""""""""" -If set to ``true``, upload any artifacts matched by the -:ref:`dist_glob_patterns ` to the release created -in the remote VCS corresponding to the latest tag. Artifacts are only uploaded if -release artifact uploads are supported by the :ref:`VCS type `. +**Type:** ``list[str]`` -**Default:** ``true`` +Similar to :ref:`config-version_variables`, but allows the version number to be +identified safely in a toml file like ``pyproject.toml``, with each entry using +dotted notation to indicate the key for which the value represents the version: + +.. code-block:: toml + + [semantic_release] + version_toml = [ + "pyproject.toml:tool.poetry.version", + ] + +**Default:** ``[]`` + +---- + +.. _config-version_variables: + +``version_variables`` +""""""""""""""""""""" + +**Type:** ``list[str]`` + +Each entry represents a location where the version is stored in the source code, +specified in ``file:variable`` format. For example: + +.. code-block:: toml + + [semantic_release] + version_variables = [ + "semantic_release/__init__.py:__version__", + "docs/conf.py:version", + ] + +**Default:** ``[]``