python-semantic-release 9.21.0__tar.gz → 10.0.0__tar.gz

{python_semantic_release-9.21.0 → python_semantic_release-10.0.0}/MANIFEST.in

@@ -2,5 +2,11 @@
 graft src/**/data/
 
 # include docs & testing into sdist, ignored for wheel build
-graft tests/
 graft docs/
+prune docs/_build/
+graft tests/
+prune tests/gh_action/
+
+# Remove any generated files
+prune **/__pycache__/
+prune src/*.egg-info

{python_semantic_release-9.21.0/src/python_semantic_release.egg-info → python_semantic_release-10.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-semantic-release
-Version: 9.21.0
+Version: 10.0.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT
@@ -20,18 +20,17 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.8
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-License-File: AUTHORS.rst
-Requires-Dist: click~=8.0
+Requires-Dist: click~=8.1.0
 Requires-Dist: click-option-group~=0.5
 Requires-Dist: gitpython~=3.0
 Requires-Dist: requests~=2.25
 Requires-Dist: jinja2~=3.1
-Requires-Dist: python-gitlab~=4.0
+Requires-Dist: python-gitlab<6.0.0,>=4.0.0
 Requires-Dist: tomlkit~=0.11
 Requires-Dist: dotty-dict~=1.3
 Requires-Dist: importlib-resources~=6.0
 Requires-Dist: pydantic~=2.0
-Requires-Dist: rich~=13.0
+Requires-Dist: rich~=14.0
 Requires-Dist: shellingham~=1.5
 Requires-Dist: Deprecated~=1.2
 Provides-Extra: build
@@ -49,7 +48,7 @@ Requires-Dist: freezegun~=1.5; extra == "test"
 Requires-Dist: pyyaml~=6.0; extra == "test"
 Requires-Dist: pytest~=8.3; extra == "test"
 Requires-Dist: pytest-clarity~=1.0; extra == "test"
-Requires-Dist: pytest-cov~=5.0; extra == "test"
+Requires-Dist: pytest-cov<7.0.0,>=5.0.0; extra == "test"
 Requires-Dist: pytest-env~=1.0; extra == "test"
 Requires-Dist: pytest-lazy-fixtures~=1.1.1; extra == "test"
 Requires-Dist: pytest-mock~=3.0; extra == "test"
@@ -67,6 +66,7 @@ Requires-Dist: mypy==1.15.0; extra == "mypy"
 Requires-Dist: types-Deprecated~=1.2; extra == "mypy"
 Requires-Dist: types-requests~=2.32.0; extra == "mypy"
 Requires-Dist: types-pyyaml~=6.0; extra == "mypy"
+Dynamic: license-file
 
 Python Semantic Release
 ***********************

{python_semantic_release-9.21.0/docs → python_semantic_release-10.0.0/docs/api}/commands.rst

@@ -1,7 +1,7 @@
 .. _commands:
 
-Commands
-========
+Command Line Interface (CLI)
+============================
 
 All commands accept a ``-h/--help`` option, which displays the help text for the
 command and exits immediately.
@@ -23,10 +23,11 @@ Correct::
    semantic-release -vv --noop version --print
 
 With the exception of :ref:`cmd-main` and :ref:`cmd-generate-config`, all
-commands require that you have set up your project's configuration. To help with
-this step, :ref:`cmd-generate-config` can create the default configuration for you,
-which will allow you to tweak it to your needs rather than write it from scratch.
+commands require that you have set up your project's configuration.
 
+To help with setting up your project configuration, :ref:`cmd-generate-config`
+will print out the default configuration to the console, which
+you can then modify it to match your project & environment.
 
 .. _cmd-main:
 

{python_semantic_release-9.21.0/docs → python_semantic_release-10.0.0/docs/concepts}/changelog_templates.rst

@@ -248,7 +248,7 @@ Configuration Examples
 
 If identified or supported by the parser, the default changelog templates will include
 a separate section of breaking changes and additional release information. Refer to the
-:ref:`commit parsing <commit-parsing>` section to see how to write commit messages that
+:ref:`commit parsing <commit_parsing>` section to see how to write commit messages that
 will be properly parsed and displayed in these sections.
 
 
@@ -331,7 +331,7 @@ be copied to its target location without being rendered by the template engine.
     When initially starting out at customizing your own changelog templates, you
     should reference the default template embedded within PSR. The template directory
     is located at ``data/templates/`` within the PSR package. Within our templates
-    directory we separate out each type of commit parser (e.g. angular) and the
+    directory we separate out each type of commit parser (e.g. conventional) and the
     content format type (e.g. markdown). You can copy this directory to your
     repository's templates directory and then customize the templates to your liking.
 

{python_semantic_release-9.21.0/docs → python_semantic_release-10.0.0/docs/concepts}/commit_parsing.rst

@@ -1,4 +1,4 @@
-.. _commit-parsing:
+.. _commit_parsing:
 
 Commit Parsing
 ==============
@@ -294,6 +294,11 @@ Guidelines`_ with all different commit types. Because of this small variance, th
 only extends our :ref:`commit_parser-builtin-angular` parser with pre-defined scipy commit types
 in the default Scipy Parser Options and all other features are inherited.
 
+**Limitations**:
+
+- Commits with the ``REV`` type are not currently supported. Track the implementation
+  of this feature in the issue `#402`_.
+
 If no commit parser options are provided via the configuration, the parser will use PSR's
 built-in :py:class:`defaults <semantic_release.commit_parser.scipy.ScipyParserOptions>`.
 
@@ -636,7 +641,7 @@ should inherit from the
 The "options" class is used to validate the options which are configured in the repository,
 and to provide default values for these options where appropriate.
 
-.. _commit-parsing-commit-parsers:
+.. _commit_parsing-commit-parsers:
 
 Commit Parsers
 """"""""""""""

python_semantic_release-10.0.0/docs/concepts/getting_started.rst

@@ -0,0 +1,391 @@
+.. _getting-started-guide:
+
+Getting Started
+===============
+
+If you haven't done so already, install Python Semantic Release locally following the
+:ref:`installation instructions <installation>`.
+
+If you are using a CI/CD service, you may not have to add Python Semantic Release to your
+project's dependencies permanently, but for the duration of this guide for the initial
+setup, you will need to have it installed locally.
+
+
+Configuring PSR
+---------------
+
+Python Semantic Release ships with a reasonable default configuration but some aspects **MUST** be
+customized to your project. To view the default configuration, run the following command:
+
+.. code-block:: bash
+
+    semantic-release generate-config
+
+The output of the above command is the default configuration in TOML format without any modifications.
+If this is fine for your project, then you do not need to configure anything else.
+
+PSR accepts overrides to the default configuration keys individually. If you don't define the
+key-value pair in your configuration file, the default value will be used.
+
+By default, Python Semantic Release will look for configuration overrides in ``pyproject.toml`` under
+the TOML table ``[tool.semantic_release]``. You may specify a different file using the
+``-c/--config`` option, for example:
+
+.. code-block:: bash
+
+    # In TOML format with top level table [semantic_release]
+    semantic-release -c releaserc.toml
+
+    # In JSON format with top level object key {"semantic_release": {}}
+    semantic-release -c releaserc.json
+
+The easiest way to get started is to output the default configuration to a file,
+delete keys you do not need to override, and then edit the remaining keys to suit your project.
+
+To set up in ``pyproject.toml``, run the following command:
+
+.. code-block:: bash
+
+    # In file redirect in bash
+    semantic-release generate-config --pyproject >> pyproject.toml
+
+    # Open your editor to edit the configuration
+    vim pyproject.toml
+
+.. seealso::
+   - :ref:`cmd-generate-config`
+   - :ref:`configuration`
+
+
+Configuring the Version Stamp Feature
+'''''''''''''''''''''''''''''''''''''
+
+One of the best features of Python Semantic Release is the ability to automatically stamp the
+new version number into your project files, so you don't have to manually update the version upon
+each release. The version that is stamped is automatically determined by Python Semantic Release
+from your commit messages which compliments automated versioning seamlessly.
+
+The most crucial version stamp is the one in your project metadata, which is used by
+the Python Package Index (PyPI) and other package managers to identify the version of your package.
+
+For Python projects, this is typically the ``version`` field in your ``pyproject.toml`` file. First,
+set up your project metadata with the base ``version`` value. If you are starting with a brand new project,
+set ``project.version = "0.0.0"``.  If you are working on an existing project, set it to the last
+version number you released. Do not include any ``v`` prefix.
+
+.. important::
+   The version number must be a valid SemVer version, which means it should follow the format
+   ``MAJOR.MINOR.PATCH`` (e.g., ``1.0.0``). Python Semantic Release does NOT support Canonical
+   version values defined in the `PEP 440`_ specification at this time. See
+   `Issue #455 <https://github.com/python-semantic-release/python-semantic-release/issues/455>`_
+   for more details. Note that you can still define a SemVer version in the ``project.version``
+   field, and when your build is generated, the build tool will automatically generate a PEP 440
+   compliant version as long as you do **NOT** use a non-pep440 compliant pre-release token.
+
+.. _PEP 440: https://peps.python.org/pep-0440/
+
+Your project metadata might look like this in ``pyproject.toml``::
+
+   [project]
+   name = "my-package"
+   version = "0.0.0"  # Set this to the last released version or "0.0.0" for new projects
+   description = "A sample Python package"
+
+To configure PSR to automatically update this version number, you need to specify the file and value
+to update in your configuration. Since ``pyproject.toml`` uses TOML format, you will add the
+replacement specification to the ``tool.semantic_release.version_toml`` list. Update the following
+configuration in your ``pyproject.toml`` file to include the version variable location:
+
+.. code-block:: toml
+
+    [tool.semantic_release]
+    version_toml = ["pyproject.toml:project.version"]
+
+    # Alternatively, if you are using poetry's 'version' key, then you would use:
+    version_toml = ["pyproject.toml:tool.poetry.version"]
+
+If you have other TOML files where you want to stamp the version, you can add them to the
+``version_toml`` list as well. In the above example, there is an implicit assumption that
+you only want the version as the raw number format. If you want to specify the full tag
+value (e.g. v-prefixed version), then include ``:tf`` for "tag format" at the end of the
+version variable specification.
+
+For non-TOML formatted files (such as JSON or YAML files), you can use the
+:ref:`config-version_variables` configuration key instead. This feature uses an advanced
+Regular Expression to find and replace the version variable in the specified files.
+
+For Python files, its much more effective to use ``importlib`` instead which will allow you to
+dynamically import the version from your package metadata and not require your project to commit
+the version number bump to the repository. For example, in your package's base ``__init__.py``
+
+.. code-block:: python
+
+    # my_package/__init__.py
+    from importlib.metadata import version as get_version
+
+    __version__ = get_version(__package__)
+    # Note: __package__ must match your 'project.name' as defined in pyproject.toml
+
+.. seealso::
+    - Configuration specification of :ref:`config-version_toml`
+    - Configuration specification of :ref:`config-version_variables`
+
+
+Using PSR to Build your Project
+'''''''''''''''''''''''''''''''
+
+PSR provides a convenient way to build your project artifacts as part of the versioning process
+now that you have stamped the version into your project files. To enable this, you will need
+to specify the build command in your configuration. This command will be executed after
+the next version has been determined, and stamped into your files but before a release tag has
+been created.
+
+To set up the build command, add the following to your ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+    [tool.semantic_release]
+    build_command = "python -m build --sdist --wheel ."
+
+.. seealso::
+   - :ref:`config-build_command` - Configuration specification for the build command.
+   - :ref:`config-build_command_env` - Configuration specification for the build command environment variables.
+
+
+Choosing a Commit Message Parser
+''''''''''''''''''''''''''''''''
+
+PSR uses commit messages to determine the type of version bump that should be applied
+to your project. PSR supports multiple commit message parsing styles, allowing you to choose
+the one that best fits your project's needs. Choose **one** of the supported commit parsers
+defined in :ref:`commit_parsing`, or provide your own and configure it in your
+``pyproject.toml`` file.
+
+Each commit parser has its own default configuration options so if you want to customize the parser
+behavior, you will need to specify the parser options you want to override.
+
+.. code-block:: toml
+
+    [tool.semantic_release]
+    commit_parser = "conventional"
+
+    [tool.semantic_release.commit_parser_options]
+    minor_tags = ["feat"]
+    patch_tags = ["fix", "perf"]
+    parse_squash_commits = true
+    ignore_merge_commits = true
+
+.. important::
+    Python Semantic Release does not currently support Monorepo projects. You will need to provide
+    a custom commit parser that is built for Monorepos. Follow the Monorepo-support progress in
+    `Issue #168 <https://github.com/python-semantic-release/python-semantic-release/issues/168>`_,
+    `Issue #614 <https://github.com/python-semantic-release/python-semantic-release/issues/614>`_,
+    and `PR #1143 <https://github.com/python-semantic-release/python-semantic-release/pull/1143>`_.
+
+
+Choosing your Changelog
+'''''''''''''''''''''''
+
+Prior to creating a release, PSR will generate a changelog from the commit messages of your
+project. The changelog is extremely customizable from the format to the content of each section.
+PSR ships with a default changelog template that will be used if you do not provide custom
+templates. The default should be sufficient for most projects and has its own set of configuration
+options.
+
+For basic customization, you can choose either an traditional Markdown formatted changelog (default)
+or if you want to integrate with a Sphinx Documentation project, you can use the
+reStructuredText (RST) format. You can also choose the file name and location of where to write the
+default changelog.
+
+To set your changelog location and changelog format, add the following to your ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+    [tool.semantic_release.changelog.default_templates]
+    changelog_file = "docs/source/CHANGELOG.rst"
+    output_format = "rst" # or "md" for Markdown format
+
+Secondly, the more important aspect of configuring your changelog is to define Commit Exclusion
+Patterns or patterns that will be used to filter out commits from the changelog. PSR does **NOT** (yet)
+come with a built-in set of exclusion patterns, so you will need to define them yourself. These commit
+patterns should be in line with your project's commit parser configuration.
+
+To set commit exclusion patterns for a conventional commits parsers, add the following to your
+``pyproject.toml`` file:
+
+.. code-block:: toml
+
+    [tool.semantic_release.changelog.exclude_commit_patterns]
+    # Recommended patterns for conventional commits parser that is scope aware
+    exclude_commit_patterns = [
+        '''chore(?:\([^)]*?\))?: .+''',
+        '''ci(?:\([^)]*?\))?: .+''',
+        '''refactor(?:\([^)]*?\))?: .+''',
+        '''style(?:\([^)]*?\))?: .+''',
+        '''test(?:\([^)]*?\))?: .+''',
+        '''build\((?!deps\): .+)''',
+        '''Initial [Cc]ommit.*''',
+    ]
+
+.. seealso::
+   - :ref:`Changelog <config-changelog>` - Customize your changelog
+   - :ref:`changelog.mode <config-changelog-mode>` - Choose the changelog mode ('update' or 'init')
+   - :ref:`changelog-templates-migrating-existing-changelog`
+
+
+Defining your Release Branches
+''''''''''''''''''''''''''''''
+
+PSR provides a powerful feature to manage release types across multiple branches which can
+allow you to configure your project to have different release branches for different purposes,
+such as pre-release branches, beta branches, and your stable releases.
+
+.. note::
+    Most projects that do **NOT** publish pre-releases will be fine with PSR's built-in default.
+
+To define an alpha pre-release branch when you are working on a fix or new feature, you can
+add the following to your ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+    [tool.semantic_release.branches.alpha]
+    # Matches branches with the prefixes 'feat/', 'fix/', or 'perf/'.
+    match = "^(feat|fix|perf)/.+"
+    prerelease = true
+    prerelease_token = "alpha"
+
+Any time you execute ``semantic-release version`` on a branch with the prefix
+``feat/``, ``fix/``, or ``perf/``, PSR will determine if a version bump is needed and if so,
+the resulting version will be a pre-release version with the ``alpha`` token. For example,
+
++-----------+--------------+-----------------+-------------------+
+| Branch    | Version Bump | Current Version | Next Version      |
++===========+==============+=================+===================+
+| main      | Patch        | ``1.0.0``       | ``1.0.1``         |
++-----------+--------------+-----------------+-------------------+
+| fix/bug-1 | Patch        | ``1.0.0``       | ``1.0.1-alpha.1`` |
++-----------+--------------+-----------------+-------------------+
+
+.. seealso::
+   - :ref:`multibranch-releases` - Learn about multi-branch releases and how to configure them.
+
+
+Configuring VCS Releases
+''''''''''''''''''''''''
+
+You can set up Python Semantic Release to create Releases in your remote version
+control system, so you can publish assets and release notes for your project.
+
+In order to do so, you will need to place an authentication token in the
+appropriate environment variable so that Python Semantic Release can authenticate
+with the remote VCS to push tags, create releases, or upload files.
+
+GitHub (``GH_TOKEN``)
+"""""""""""""""""""""
+
+For local publishing to GitHub, you should use a personal access token and
+store it in your environment variables. Specify the name of the environment
+variable in your configuration setting :ref:`remote.token <config-remote-token>`.
+The default is ``GH_TOKEN``.
+
+To generate a token go to https://github.com/settings/tokens and click on
+"Generate new token".
+
+For Personal Access Token (classic), you will need the ``repo`` scope to write
+(ie. push) to the repository.
+
+For fine-grained Personal Access Tokens, you will need the `contents`__
+permission.
+
+__ https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens#repository-permissions-for-contents
+
+GitLab (``GITLAB_TOKEN``)
+"""""""""""""""""""""""""
+
+A personal access token from GitLab. This is used for authenticating when pushing
+tags, publishing releases etc. This token should be stored in the ``GITLAB_TOKEN``
+environment variable.
+
+Gitea (``GITEA_TOKEN``)
+"""""""""""""""""""""""
+
+A personal access token from Gitea. This token should be stored in the ``GITEA_TOKEN``
+environment variable.
+
+Bitbucket (``BITBUCKET_TOKEN``)
+"""""""""""""""""""""""""""""""
+
+Bitbucket does not support uploading releases but can still benefit from automated tags
+and changelogs. The user has three options to push changes to the repository:
+
+#. Use SSH keys.
+
+#. Use an `App Secret`_, store the secret in the ``BITBUCKET_TOKEN`` environment variable
+   and the username in ``BITBUCKET_USER``.
+
+#. Use an `Access Token`_ for the repository and store it in the ``BITBUCKET_TOKEN``
+   environment variable.
+
+.. _App Secret: https://support.atlassian.com/bitbucket-cloud/docs/push-back-to-your-repository/#App-secret
+.. _Access Token: https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens
+
+.. seealso::
+   - :ref:`Changelog <config-changelog>` - customize your project's changelog.
+
+   - :ref:`changelog-templates-custom_release_notes` - customize the published release notes
+
+   - :ref:`version --vcs-release/--no-vcs-release <cmd-version-option-vcs-release>` - enable/disable VCS release
+     creation.
+
+
+Testing your Configuration
+--------------------------
+
+It's time to test your configuration!
+
+.. code-block:: bash
+
+    # 1. Run the command in no-operation mode to see what would happen
+    semantic-release -v --noop version
+
+    # 2. If the output looks reasonable, try to run the command without any history changes
+    #    '-vv' will give you verbose debug output, which is useful for troubleshooting
+    #    commit parsing issues.
+    semantic-release -vv version --no-commit --no-tag
+
+    # 3. Evaluate your repository to see the changes that were made but not committed
+    #    - Check the version number in your pyproject.toml
+    #    - Check the distribution files from the build command
+    #    - Check the changelog file for the new release notes
+
+    # 4. If everything looks good, make sure to commit/save your configuration changes
+    git add pyproject.toml
+    git commit -m "chore(config): configure Python Semantic Release"
+
+    # 5. Now, try to run the release command with your history changes but without pushing
+    semantic-release -v version --no-push --no-vcs-release
+
+    # 6. Check the result on your local repository
+    git status
+    git log --graph --decorate --all
+
+    # 7a. If you are happy with the release history and resulting commit & tag,
+    #     reverse your changes before trying the full release command.
+    git tag -d v0.0.1  # replace with the actual version you released
+    git reset --hard HEAD~1
+
+    # 7b. [Optional] Once you have configured a remote VCS token, try
+    #     running the full release command to update the remote repository.
+    semantic-release version --push --vcs-release
+    #    This is optional as you may not want a personal access token set up or make
+    #    make the release permanent yet.
+
+.. seealso::
+   - :ref:`cmd-version`
+   - :ref:`troubleshooting-verbosity`
+
+Configuring CI/CD
+-----------------
+
+PSR is meant to help you release at speed! See our CI/CD Configuration guides under the
+:ref:`automatic` section.

python_semantic_release-10.0.0/docs/concepts/index.rst

@@ -0,0 +1,17 @@
+.. _concepts:
+
+Concepts
+========
+
+This section covers the core concepts of Python Semantic Release and how it
+works. Understanding these concepts will help you effectively use Python
+Semantic Release in your projects.
+
+.. toctree::
+    :maxdepth: 1
+
+    getting_started
+    commit_parsing
+    changelog_templates
+    multibranch_releases
+    strict_mode

python_semantic_release-10.0.0/docs/concepts/installation.rst

@@ -0,0 +1,14 @@
+.. _installation:
+
+Installation
+============
+
+.. code-block:: bash
+
+  python3 -m pip install python-semantic-release
+  semantic-release --help
+
+Python Semantic Release is also available from `conda-forge`_ or as a
+:ref:`GitHub Action <gh_actions>`.
+
+.. _conda-forge: https://anaconda.org/conda-forge/python-semantic-release

{python_semantic_release-9.21.0 → python_semantic_release-10.0.0}/docs/conf.py

@@ -1,5 +1,6 @@
 import os
 import sys
+from datetime import datetime, timezone
 
 sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, os.path.abspath(".."))
@@ -24,7 +25,8 @@ templates_path = ["_templates"]
 source_suffix = ".rst"
 master_doc = "index"
 project = "python-semantic-release"
-copyright = f"2024, {author_name}"  # noqa: A001
+current_year = datetime.now(timezone.utc).astimezone().year
+copyright = f"{current_year}, {author_name}"  # noqa: A001
 
 version = semantic_release.__version__
 release = semantic_release.__version__
@@ -39,7 +41,7 @@ htmlhelp_basename = "python-semantic-releasedoc"
 # -- Automatically run sphinx-apidoc --------------------------------------
 
 docs_path = os.path.dirname(__file__)
-apidoc_output_dir = os.path.join(docs_path, "api")
+apidoc_output_dir = os.path.join(docs_path, "api", "modules")
 apidoc_module_dir = os.path.join(docs_path, "..", "src")
 apidoc_separate_modules = True
 apidoc_module_first = True

{python_semantic_release-9.21.0/docs → python_semantic_release-10.0.0/docs/configuration}/automatic-releases/cronjobs.rst

@@ -1,7 +1,7 @@
 .. _cronjobs:
 
-Publish with cronjobs
-~~~~~~~~~~~~~~~~~~~~~
+Cron Job Publishing
+===================
 
 This is for you if for some reason you cannot publish from your CI or you would like releases to
 drop at a certain interval. Before you start, answer this: Are you sure you do not want a CI to