Mar 1, 2025 · Feb 6, 2025 · Feb 6, 2025 · Feb 6, 2025 · Feb 6, 2025 · Feb 7, 2025
diff --git a/.github/workflows/assets/release_template.html b/.github/workflows/assets/release_template.html
 <b>We've just released {tag}</b>.
 Thank you to everyone who contributed to this release.
 As usual, upgrade using<code>pip install -U python-telegram-bot</code>.

 The release notes can be found<ahref="https://docs.python-telegram-bot.org/en/{tag}/changelog.html">here</a>.
diff --git a/.github/workflows/chango_fragment.yml b/.github/workflows/chango_fragment.yml
 name: Create Chango Fragment
 on:
  pull_request:
    types:
      - opened
      - reopened

 permissions: {}

 jobs:
  create-chango-fragment:
    permissions:
      # Give the default GITHUB_TOKEN write permission to commit and push the
      # added or changed files to the repository.
      contents: write
    name: create-chango-fragment
    runs-on: ubuntu-latest
    steps:

      # Create the new fragment
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false
      - uses: Bibo-Joshi/chango@176c53372d1f8c0f1f6caabde100077bc45d41cc # v0.3.1
        with:
          github-token: ${{ secrets.CHANGO_PAT }}
          query-issue-types: true


diff --git a/.github/workflows/docs-admonitions.yml b/.github/workflows/docs-admonitions.yml
      actions: write
    strategy:
      matrix:
        python-version: ['3.10']
        python-version: ['3.12']
        os: [ubuntu-latest]
      fail-fast: False
    steps:
diff --git a/.github/workflows/docs-linkcheck.yml b/.github/workflows/docs-linkcheck.yml
    runs-on: ${{matrix.os}}
    strategy:
      matrix:
        python-version: ['3.10']
        python-version: ['3.12']
        os: [ubuntu-latest]
      fail-fast: False
    steps:
diff --git a/.github/workflows/release_pypi.yml b/.github/workflows/release_pypi.yml
        env:
          GITHUB_TOKEN: ${{ github.token }}
          TAG: ${{ needs.build.outputs.TAG }}
        # Create a tag and a GitHub Release. The descriptioncan be changed later, as for now
        #we don't define it through this workflow.
        # Create a tag and a GitHub Release. The descriptionis filled by the static template, we
        #just insert the correct tag in the template.
        run: >-
          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
          gh release create
          "$TAG"
          --repo '${{ github.repository }}'
          --generate-notes
          --notes-file -
      - name: Upload artifact signatures to GitHub Release
        env:
          GITHUB_TOKEN: ${{ github.token }}
          gh release upload
          "$TAG" dist/**
          --repo '${{ github.repository }}'

  telegram-channel:
    name: Publish to Telegram Channel
    needs:
        - github-release

    runs-on: ubuntu-latest
    environment:
      name: release_pypi
    permissions: {}

    steps:
      - name: Publish to Telegram Channel
        env:
          TAG: ${{ needs.build.outputs.TAG }}
          # This secret is configured only for the `pypi-release` branch
          BOT_TOKEN: ${{ secrets.CHANNEL_BOT_TOKEN }}
        run: >-
          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
          curl
          -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage"
          -d "chat_id=@pythontelegrambotchannel"
          -d "parse_mode=HTML"
          --data-urlencode "text@-"
diff --git a/.github/workflows/release_test_pypi.yml b/.github/workflows/release_test_pypi.yml
        env:
          GITHUB_TOKEN: ${{ github.token }}
          TAG: ${{ needs.build.outputs.TAG }}
        # Create a GitHub Release *draft*. The descriptioncan be changed later, as for now
        # wedon't define it through this workflow.
        # Create atag and aGitHub Release *draft*. The descriptionis filled by the static
        #template,wejust insert the correct tag in the template.
        run: >-
          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
          gh release create
          "$TAG"
          --repo '${{ github.repository }}'
          --generate-notes
          --draft
          --notes-file -
      - name: Upload artifact signatures to GitHub Release
        env:
          GITHUB_TOKEN: ${{ github.token }}
diff --git a/CHANGES.rst → changes/LEGACY.rst b/CHANGES.rst → changes/LEGACY.rst
 .. _ptb-changelog:

 =========
 Changelog
 =========

 Version 21.11.1
 ===============

diff --git a/changes/config.py b/changes/config.py
 # noqa: INP001
 # pylint: disable=import-error
 """Configuration for the chango changelog tool"""

 from collections.abc import Collection
 from typing import Optional

 from chango.concrete import DirectoryChanGo, DirectoryVersionScanner, HeaderVersionHistory
 from chango.concrete.sections import GitHubSectionChangeNote, Section, SectionVersionNote

 version_scanner = DirectoryVersionScanner(base_directory=".", unreleased_directory="unreleased")


 class ChangoSectionChangeNote(
    GitHubSectionChangeNote.with_sections(  # type: ignore[misc]
        [
            Section(uid="highlights", title="Highlights", sort_order=0),
            Section(uid="breaking", title="Breaking Changes", sort_order=1),
            Section(uid="security", title="Security Changes", sort_order=2),
            Section(uid="deprecations", title="Deprecations", sort_order=3),
            Section(uid="features", title="New Features", sort_order=4),
            Section(uid="bugfixes", title="Bug Fixes", sort_order=5),
            Section(uid="dependencies", title="Dependencies", sort_order=6),
            Section(uid="other", title="Other Changes", sort_order=7),
            Section(uid="documentation", title="Documentation", sort_order=8),
            Section(uid="internal", title="Internal Changes", sort_order=9),
        ]
    )
 ):
    """Custom change note type for PTB. Mainly overrides get_sections to map labels to sections"""

    OWNER = "python-telegram-bot"
    REPOSITORY = "python-telegram-bot"

    @classmethod
    def get_sections(
        cls,
        labels: Collection[str],
        issue_types: Optional[Collection[str]],
    ) -> set[str]:
        """Override get_sections to have customized auto-detection of relevant sections based on
        the pull request and linked issues. Certainly not perfect in all cases, but should be a
        good start for most PRs.
        """
        combined_labels = set(labels) | (set(issue_types or []))

        mapping = {
            "🐛 bug": "bugfixes",
            "💡 feature": "features",
            "🧹 chore": "internal",
            "⚙️ bot-api": "features",
            "⚙️ documentation": "documentation",
            "⚙️ tests": "internal",
            "⚙️ ci-cd": "internal",
            "⚙️ security": "security",
            "⚙️ examples": "documentation",
            "⚙️ type-hinting": "other",
            "🛠 refactor": "internal",
            "🛠 breaking": "breaking",
            "⚙️ dependencies": "dependencies",
            "🔗 github-actions": "internal",
            "🛠 code-quality": "internal",
        }

        # we want to return *all* from the mapping that are in the combined_labels
        # removing superfluous sections from the fragment is a tad easier than adding them
        found = {section for label, section in mapping.items() if label in combined_labels}

        # if we have not found any sections, we default to "other"
        return found or {"other"}


 chango_instance = DirectoryChanGo(
    change_note_type=ChangoSectionChangeNote,
    version_note_type=SectionVersionNote,
    version_history_type=HeaderVersionHistory,
    scanner=version_scanner,
 )
diff --git a/changes/unreleased/.gitkeep b/changes/unreleased/.gitkeep
diff --git a/changes/unreleased/4672.G9szuJ7pRafycByfem2DrT.toml b/changes/unreleased/4672.G9szuJ7pRafycByfem2DrT.toml
 documentation = "Add `chango <https://chango.readthedocs.io/stable/>`_ As Changelog Management Tool"
 [[pull_requests]]
 uid = "4672"
 author_uid = "Bibo-Joshi"
 closes_threads = ["4321"]
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
 chango~=0.3.2
 sphinx==8.1.3
 furo==2024.8.6
 furo-sphinx-search @ git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
 .. include:: ../../CHANGES.rst
 .. _ptb-changelog:

 =========
 Changelog
 =========

 .. chango::

 .. include:: ../../changes/LEGACY.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 from sphinx.application import Sphinx

 if sys.version_info < (3, 12):
    # Due to dependency on chango
    raise RuntimeError("This documentation needs at least Python 3.12")


 sys.path.insert(0, str(Path("../..").resolve().absolute()))

 # -- General configuration ------------------------------------------------
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
    "chango.sphinx_ext",
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
 if os.environ.get("READTHEDOCS", "") == "True":
    extensions.append("sphinx_build_compatibility.extension")

 # Configuration for the chango sphinx directive
 chango_pyproject_toml_path = Path(__file__).parent.parent.parent

 # For shorter links to Wiki in docstrings
 extlinks = {
    "wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s"),
diff --git a/pyproject.toml b/pyproject.toml
 [tool.hatch.build]
 packages = ["telegram"]

 # CHANGO
 [tool.chango]
 sys_path = "changes"
 chango_instance = { name= "chango_instance", module = "config" }

 # BLACK:
 [tool.black]
 line-length = 99
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,5 @@
		<b>We've just released {tag}</b>.
		Thank you to everyone who contributed to this release.
		As usual, upgrade using<code>pip install -U python-telegram-bot</code>.

		The release notes can be found<ahref="https://docs.python-telegram-bot.org/en/{tag}/changelog.html">here</a>.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,29 @@
		name: Create Chango Fragment
		on:
		pull_request:
		types:
		- opened
		- reopened

		permissions: {}

		jobs:
		create-chango-fragment:
		permissions:
		# Give the default GITHUB_TOKEN write permission to commit and push the
		# added or changed files to the repository.
		contents: write
		name: create-chango-fragment
		runs-on: ubuntu-latest
		steps:

		# Create the new fragment
		- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
		with:
		persist-credentials: false
		- uses: Bibo-Joshi/chango@176c53372d1f8c0f1f6caabde100077bc45d41cc # v0.3.1
		with:
		github-token: ${{ secrets.CHANGO_PAT }}
		query-issue-types: true
Original file line number	Diff line number	Diff line change
Expand Up		@@ -20,7 +20,7 @@ jobs:
		actions: write
		strategy:
		matrix:
		python-version: ['3.10']
		python-version: ['3.12']
		os: [ubuntu-latest]
		fail-fast: False
		steps:
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -15,7 +15,7 @@ jobs:
		runs-on: ${{matrix.os}}
		strategy:
		matrix:
		python-version: ['3.10']
		python-version: ['3.12']
		os: [ubuntu-latest]
		fail-fast: False
		steps:
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -119,13 +119,14 @@ jobs:
		env:
		GITHUB_TOKEN: ${{ github.token }}
		TAG: ${{ needs.build.outputs.TAG }}
		# Create a tag and a GitHub Release. The descriptioncan be changed later, as for now
		#we don't define it through this workflow.
		# Create a tag and a GitHub Release. The descriptionis filled by the static template, we
		#just insert the correct tag in the template.
		run: >-
		sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html \|
		gh release create
		"$TAG"
		--repo '${{ github.repository }}'
		--generate-notes
		--notes-file -
		- name: Upload artifact signatures to GitHub Release
		env:
		GITHUB_TOKEN: ${{ github.token }}
Expand All		@@ -137,3 +138,27 @@ jobs:
		gh release upload
		"$TAG" dist/**
		--repo '${{ github.repository }}'

		telegram-channel:
		name: Publish to Telegram Channel
		needs:
		- github-release

		runs-on: ubuntu-latest
		environment:
		name: release_pypi
		permissions: {}

		steps:
		- name: Publish to Telegram Channel
		env:
		TAG: ${{ needs.build.outputs.TAG }}
		# This secret is configured only for the `pypi-release` branch
		BOT_TOKEN: ${{ secrets.CHANNEL_BOT_TOKEN }}
		run: >-
		sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html \|
		curl
		-X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage"
		-d "chat_id=@pythontelegrambotchannel"
		-d "parse_mode=HTML"
		--data-urlencode "text@-"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -121,14 +121,15 @@ jobs:
		env:
		GITHUB_TOKEN: ${{ github.token }}
		TAG: ${{ needs.build.outputs.TAG }}
		# Create a GitHub Release draft. The descriptioncan be changed later, as for now
		# wedon't define it through this workflow.
		# Create atag and aGitHub Release draft. The descriptionis filled by the static
		#template,wejust insert the correct tag in the template.
		run: >-
		sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html \|
		gh release create
		"$TAG"
		--repo '${{ github.repository }}'
		--generate-notes
		--draft
		--notes-file -
		- name: Upload artifact signatures to GitHub Release
		env:
		GITHUB_TOKEN: ${{ github.token }}
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,9 +1,3 @@
		.. _ptb-changelog:

		=========
		Changelog
		=========

		Version 21.11.1
		===============

Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,78 @@
		# noqa: INP001
		# pylint: disable=import-error
		"""Configuration for the chango changelog tool"""

		from collections.abc import Collection
		from typing import Optional

		from chango.concrete import DirectoryChanGo, DirectoryVersionScanner, HeaderVersionHistory
		from chango.concrete.sections import GitHubSectionChangeNote, Section, SectionVersionNote

		version_scanner = DirectoryVersionScanner(base_directory=".", unreleased_directory="unreleased")


		class ChangoSectionChangeNote(
		GitHubSectionChangeNote.with_sections( # type: ignore[misc]
		[
		Section(uid="highlights", title="Highlights", sort_order=0),
		Section(uid="breaking", title="Breaking Changes", sort_order=1),
		Section(uid="security", title="Security Changes", sort_order=2),
		Section(uid="deprecations", title="Deprecations", sort_order=3),
		Section(uid="features", title="New Features", sort_order=4),
		Section(uid="bugfixes", title="Bug Fixes", sort_order=5),
		Section(uid="dependencies", title="Dependencies", sort_order=6),
		Section(uid="other", title="Other Changes", sort_order=7),
		Section(uid="documentation", title="Documentation", sort_order=8),
		Section(uid="internal", title="Internal Changes", sort_order=9),
		]
		)
		):
		"""Custom change note type for PTB. Mainly overrides get_sections to map labels to sections"""

		OWNER = "python-telegram-bot"
		REPOSITORY = "python-telegram-bot"

		@classmethod
		def get_sections(
		cls,
		labels: Collection[str],
		issue_types: Optional[Collection[str]],
		) -> set[str]:
		"""Override get_sections to have customized auto-detection of relevant sections based on
		the pull request and linked issues. Certainly not perfect in all cases, but should be a
		good start for most PRs.
		"""
		combined_labels = set(labels) \| (set(issue_types or []))

		mapping = {
		"🐛 bug": "bugfixes",
		"💡 feature": "features",
		"🧹 chore": "internal",
		"⚙️ bot-api": "features",
		"⚙️ documentation": "documentation",
		"⚙️ tests": "internal",
		"⚙️ ci-cd": "internal",
		"⚙️ security": "security",
		"⚙️ examples": "documentation",
		"⚙️ type-hinting": "other",
		"🛠 refactor": "internal",
		"🛠 breaking": "breaking",
		"⚙️ dependencies": "dependencies",
		"🔗 github-actions": "internal",
		"🛠 code-quality": "internal",
		}

		# we want to return all from the mapping that are in the combined_labels
		# removing superfluous sections from the fragment is a tad easier than adding them
		found = {section for label, section in mapping.items() if label in combined_labels}

		# if we have not found any sections, we default to "other"
		return found or {"other"}


		chango_instance = DirectoryChanGo(
		change_note_type=ChangoSectionChangeNote,
		version_note_type=SectionVersionNote,
		version_history_type=HeaderVersionHistory,
		scanner=version_scanner,
		)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,5 @@
		documentation = "Add `chango <https://chango.readthedocs.io/stable/>`_ As Changelog Management Tool"
		[[pull_requests]]
		uid = "4672"
		author_uid = "Bibo-Joshi"
		closes_threads = ["4321"]
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1,4 @@
		chango~=0.3.2
		sphinx==8.1.3
		furo==2024.8.6
		furo-sphinx-search @ git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1
Expand Down