Source code for repomatic.github.release_sync

# Copyright Kevin Deldycke <[email protected]> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

"""Sync GitHub release notes from `changelog.md`.

Compares each GitHub release body against the corresponding
`changelog.md` section and updates any that have drifted.
`changelog.md` is the single source of truth.
"""

from __future__ import annotations

import logging
from dataclasses import asdict, dataclass, field

from ..changelog import GITHUB_RELEASE_URL, Changelog, availability_admonition
from ..pypi import PYPI_PROJECT_URL
from ..tabular import ReportAction, render_markdown_table
from ..templating import render_template
from .gh import GhCommandError
from .releases import (
    GitHubReleasesUnavailable,
    edit_release_notes,
    get_github_releases,
)
from .urls import parse_github_repo

TYPE_CHECKING = False
if TYPE_CHECKING:
    from pathlib import Path


[docs] def build_expected_body( changelog: Changelog, version: str, *, admonition_override: str | None = None, ) -> str: """Build the expected release body from the changelog. Decomposes the changelog section into discrete elements and renders them through the `github-releases` template. This allows the GitHub release body to include a different subset of elements than the `release-notes` template used for `changelog.md` entries. Lives here, with the release publishers, rather than in {mod}`repomatic.changelog`: every caller is a GitHub-release writer (this sync, the dev pre-release, the release-notes metadata keys), and the changelog module renders changelog entries, not release bodies. The release draft is one more: see {func}`build_draft_body`. :param changelog: Parsed changelog instance. :param version: Version string, like `1.2.3`. :param admonition_override: If provided, replaces the `availability_admonition` from the changelog. Used by {func}`build_pypi_body` to inject a pre-computed admonition at release time. :return: The rendered release body, or empty string if the version has no changelog section. """ elements = changelog.decompose_version(version) if not elements.has_body: return "" if admonition_override is not None: elements.availability_admonition = admonition_override return render_template( "github-releases", **asdict(elements), tag_range=elements.tag_range, )
[docs] def build_pypi_body(changelog: Changelog, version: str, package_name: str) -> str: """Build the release body of a version published on PyPI. The body of {func}`build_expected_body`, with the availability admonition linking to PyPI and GitHub injected before `fix-changelog` writes it into `changelog.md`. The admonition comes from {func}`~repomatic.changelog.availability_admonition`, the renderer `fix-changelog` writes the section with, so both word it the same way. The draft cannot ask the platforms which release came first: the PyPI upload runs beside it, and a failed lookup reads like an empty one. The changelog answers instead, as `lint-changelog` will once both platforms carry the release. :param changelog: Parsed changelog instance. :param version: Version string, like `1.2.3`. :param package_name: The project name on PyPI. :return: The rendered body, or an empty string when the changelog names no repository or holds no section for *version*. """ repo_url = changelog.extract_repo_url() if not repo_url: return "" first = changelog.is_first_release(version) admonition = availability_admonition( version, pypi_url=PYPI_PROJECT_URL.format(package=package_name, version=version), github_url=GITHUB_RELEASE_URL.format(repo_url=repo_url, version=version), first_on_pypi=first, first_on_github=first, ) return build_expected_body(changelog, version, admonition_override=admonition)
[docs] def build_draft_body( changelog: Changelog, version: str, package_name: str | None ) -> str: """Build the body a release draft is created with. The body carries the PyPI availability admonition from the start: baking it into the draft, rather than editing the release from the caller's fast `publish-pypi` lane, avoids a race between the lanes. That edit can run before the draft exists. The bake is optimistic: it assumes the parallel PyPI upload succeeds, which it does on the normal path, and a failed upload surfaces as a red `publish-pypi` job. :param changelog: Parsed changelog instance. :param version: Version string, like `1.2.3`. :param package_name: The project name on PyPI, or `None` for a project that does not publish there. :return: {func}`build_pypi_body` for a PyPI project, else {func}`build_expected_body`. Empty when the changelog holds no section for *version*. """ if package_name: body = build_pypi_body(changelog, version, package_name) if body: return body return build_expected_body(changelog, version)
[docs] @dataclass(frozen=True) class SyncRow: """Per-release detail for the markdown report table.""" action: ReportAction version: str release_url: str
[docs] @dataclass class SyncResult: """Accumulated results from a release-notes sync run.""" dry_run: bool = True rows: list[SyncRow] = field(default_factory=list) total: int = 0 in_sync: int = 0 drifted: int = 0 updated: int = 0 failed: int = 0 missing_changelog: int = 0
def _normalize_body(text: str) -> str: """Normalize a release body for comparison. Strips trailing whitespace from each line and trailing newlines from the whole text so insignificant formatting differences don't cause false positives. :param text: Raw release body text. :return: Normalized text. """ lines = [line.rstrip() for line in text.splitlines()] return "\n".join(lines).strip()
[docs] def sync_github_releases( repo_url: str, changelog_path: Path, dry_run: bool = True, ) -> SyncResult: """Sync GitHub release bodies from `changelog.md`. For each released version in the changelog, compares the expected body (from `changelog.md`) with the actual GitHub release body. In live mode, updates drifted releases via `gh release edit`. Live mode reads the release bodies fresh rather than from the day-long cache: an edit decided against a stale body would rewrite a release that already matches, or miss one that drifted since. :param repo_url: Repository URL (like `https://github.com/user/repo`). :param changelog_path: Path to `changelog.md`. :param dry_run: If `True`, report without making changes. :return: Structured sync results. """ result = SyncResult(dry_run=dry_run) parsed = parse_github_repo(repo_url) if parsed is None: logging.warning(f"{repo_url} names no GitHub repository.") return result repository = "/".join(parsed) content = changelog_path.read_text(encoding="UTF-8") changelog = Changelog(content) try: releases = get_github_releases(repo_url, force_refresh=not dry_run) except GitHubReleasesUnavailable as exc: # Sync is read-only relative to `changelog.md`, so skipping a run # when the API is unhealthy just defers the work to the next run. logging.warning(f"Skipping release-notes sync: {exc}") return result if not releases: logging.warning("No GitHub releases found.") return result # Iterate over released versions in the changelog. for version, _date in changelog.extract_all_releases(): result.total += 1 if version not in releases: logging.debug(f"No GitHub release for version {version}.") continue release_url = GITHUB_RELEASE_URL.format(repo_url=repo_url, version=version) expected = build_expected_body(changelog, version) if not expected: result.missing_changelog += 1 logging.debug(f"Changelog section for {version} is empty.") continue actual = releases[version].body if _normalize_body(expected) == _normalize_body(actual): result.in_sync += 1 result.rows.append( SyncRow( action=ReportAction.SKIPPED, version=version, release_url=release_url, ) ) continue result.drifted += 1 if dry_run: logging.info(f"[dry-run] Would update release notes for v{version}.") result.rows.append( SyncRow( action=ReportAction.DRY_RUN, version=version, release_url=release_url, ) ) continue # Live mode: update the release body. A failed edit is counted against # its release and the run goes on: one transient error must not leave # every release after it drifted. try: edited = edit_release_notes(f"v{version}", repository, expected) except GhCommandError: edited = False if edited: result.updated += 1 result.rows.append( SyncRow( action=ReportAction.UPDATED, version=version, release_url=release_url, ) ) logging.info(f"Updated release notes for v{version}.") else: result.failed += 1 result.rows.append( SyncRow( action=ReportAction.FAILED, version=version, release_url=release_url, ) ) logging.warning(f"Failed to update release notes for v{version}.") return result
[docs] def render_sync_report(result: SyncResult) -> str: """Render a markdown report from sync results. :param result: Structured results from the sync run. :return: Markdown report string. """ mode = "dry-run" if result.dry_run else "live" # Summary table rows. summary_lines = [ f"| \U0001f4e6 Total releases | {result.total} |", f"| \u2705 In sync | {result.in_sync} |", f"| \U0001f504 Drifted | {result.drifted} |", ] if not result.dry_run: summary_lines.extend(( f"| \u2705 Updated | {result.updated} |", f"| \u26a0\ufe0f Failed | {result.failed} |", )) if result.missing_changelog: summary_lines.append( f"| \u2753 Missing changelog | {result.missing_changelog} |" ) # Per-release details. drifted_rows = [row for row in result.rows if row.action != ReportAction.SKIPPED] details_section = "" if drifted_rows: table = render_markdown_table( ("Version", "Release", "Action"), ( ( f"`{row.version}`", f"[`v{row.version}`]({row.release_url})", row.action.value, ) for row in drifted_rows ), ) details_section = f"### \U0001f4dd Details\n\n{table}" return render_template( "release-sync-report", mode=mode, summary_rows="\n".join(summary_lines), details_section=details_section, )