Automatisieren von Python-Bibliotheksversionen mithilfe von GitHub-Aktionen und Commitizen

Einführung

Die Pflege einer Python-Bibliothek kann eine Herausforderung sein, insbesondere wenn es um die Veröffentlichung neuer Versionen geht. Der Prozess kann zeitaufwändig und fehleranfällig sein, wenn er manuell durchgeführt wird. In diesem Beitrag werde ich Sie durch die Automatisierung des Veröffentlichungsprozesses mithilfe von GitHub Actions und Commitizen führen. Dieser Ansatz stellt sicher, dass Ihre Releases konsistent sind, die semantische Versionierung (Semver) einhalten und Ihr Änderungsprotokoll auf dem neuesten Stand hält – und das alles bei gleichzeitiger Reduzierung manueller Eingriffe.

Was ist semantische Versionierung?

Semantische Versionierung (Semver) ist ein Versionierungsschema, das drei Zahlen im Format MAJOR.MINOR.PATCH verwendet. Dieses Schema bietet eine klare und vorhersehbare Möglichkeit, zu kommunizieren, was sich in jeder Version geändert hat:

• WICHTIG: Breaking Changes – alles, was nicht abwärtskompatibel ist.
• MINOR: Neue Funktionen, aber abwärtskompatibel.
• PATCH: Fehlerbehebungen – vollständig abwärtskompatibel.

Semantische Versionierung ist von entscheidender Bedeutung, da sie Entwicklern hilft, Abhängigkeiten effektiv zu verwalten. Wenn Sie wissen, dass eine neue Version einer Bibliothek keine wichtigen Änderungen mit sich bringt (z. B. ein Neben- oder Patch-Update), können Sie Ihre Abhängigkeiten getrost aktualisieren, ohne befürchten zu müssen, dass Ihre Anwendung kaputt geht.

Weitere Informationen zu Semver finden Sie auf semver.org.

Einführung in commitizen

Commitizen ist ein Tool, das Commit-Nachrichten standardisiert und die Versionierung und Änderungsprotokollerstellung automatisiert. Durch die Durchsetzung eines bestimmten Commit-Nachrichtenformats kann Commitizen die Art der erforderlichen Versionserhöhung (Hauptversion, Nebenversion oder Patch) ermitteln und automatisch ein Änderungsprotokoll erstellen.

Das Commit-Nachrichtenformat folgt dieser Struktur:

<commit-type>(<topic>): the commit message

• Commit-Typen:
  • feat: Weist auf eine neue Funktion hin. Dies kann zu einer geringfügigen Versionsverbesserung führen. Wenn ein Commit einen BREAKING CHANGE-Hinweis enthält, führt dies zu einem größeren Versionssprung.
  • Fix: Weist auf eine Fehlerbehebung hin und führt zu einer Patch-Versionserhöhung.
  • chore, ci und andere: Diese lösen keinen Versionssprung aus.

Zum Beispiel:

feat(parser): add support for parsing new file formats

fix(api): handle null values in the response

feat(api): change response of me endpoint

BREAKING CHANGE: 

changes the API signature of the parser function

In diesem Beispiel würde der Hinweis BREAKING CHANGE innerhalb eines feat-Commits einen großen Versionssprung auslösen. Diese Konsistenz stellt sicher, dass Ihre Versionsnummern den richtigen Änderungsgrad angeben, was für Benutzer, die sich auf Ihre Bibliothek verlassen, von entscheidender Bedeutung ist.

Commitizen konfigurieren

Um Commitizen in Ihr Python-Projekt zu integrieren, müssen Sie es in Ihrer pyproject.toml-Datei konfigurieren. Nachfolgend finden Sie die Konfiguration, die Sie hinzufügen müssen:

[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
tag_format = "v$version"
version_files = [
    "pyproject.toml:version",
]
update_changelog_on_bump = true

Erklärung:

• Name: Gibt die zu verwendende Commit-Nachrichtenkonvention an. Wir verwenden das herkömmliche Commits-Format.
• Version: Die aktuelle Version Ihres Projekts. Sie sollten mit „0.1.0“ oder Ihrer ursprünglichen Version beginnen.
• tag_format: Definiert, wie Tags formatiert werden, wobei v$version das typische Format ist (v1.0.0, v1.1.0 usw.).
• version_files: Listet die Dateien auf, in denen Versionsnummern verfolgt werden. Dieses Setup stellt sicher, dass die Versionsnummer in pyproject.toml automatisch aktualisiert wird.
• update_changelog_on_bump: Aktualisiert die Datei CHANGELOG.md automatisch, wenn ein Versionssprung auftritt.

Warum den Release-Prozess automatisieren?

Die manuelle Verwaltung von Releases kann mühsam und fehleranfällig sein, insbesondere wenn Ihr Projekt wächst. Automatisierung bringt mehrere entscheidende Vorteile mit sich:

• Konsistenz: Stellt sicher, dass Versionssprünge und Änderungsprotokolle jedes Mal auf die gleiche Weise gehandhabt werden.
• Effizienz: Spart Zeit durch Reduzierung der manuellen Schritte, die mit der Veröffentlichung einer neuen Version verbunden sind.
• Genauigkeit: Minimiert menschliche Fehler, wie z. B. das Vergessen, das Änderungsprotokoll zu aktualisieren oder die falsche Versionsänderung.

Überblick: Der automatisierte Freigabeprozess

Um Ihnen ein klares Bild davon zu geben, wie die Automatisierung funktioniert, finden Sie hier eine allgemeine Übersicht:

1. Beim Zusammenführen zum Hauptzweig: Wenn eine Pull-Anfrage (PR) mit dem Hauptzweig zusammengeführt wird, überprüft der Workflow die Commit-Nachrichten, entscheidet, ob ein Versionssprung erforderlich ist, aktualisiert das Änderungsprotokoll und markiert die Veröffentlichung bei Bedarf .
2. Bei der Tag-Erstellung: Wenn ein Tag gepusht wird (was auf eine neue Version hinweist), veröffentlicht der Workflow die neue Version auf PyPI und erstellt eine GitHub-Version mit dem entsprechenden Änderungsprotokoll.

Aufteilen des Workflows: Zusammenführen vs. Tag-Ereignisse

Der Einfachheit und Klarheit halber teilen wir die Automatisierung in zwei Arbeitsabläufe auf:

1. Merge to Main Workflow
2. On Tag Creation Workflow

Workflow 1: On Merge to Main

This workflow handles the logic of detecting changes and bumping the version:

name: Merge to Main

on:
  push:
    branches:
      - "main"

concurrency:
  group: main
  cancel-in-progress: true

jobs:
  bump:
    if: "!startsWith(github.event.head_commit.message, 'bump:')"
    runs-on: ubuntu-latest
    steps:
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          fetch-depth: 0
      - name: Create bump and changelog
        uses: commitizen-tools/commitizen-action@0.21.0
        with:
          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          branch: main

Explanation:

• Trigger: This workflow is triggered when a new commit is pushed to the main branch.
• Concurrency: The concurrency setting ensures that only one instance of the workflow runs at a time for the main branch, preventing race conditions and duplicate version bumps.
• bump job: It checks whether the commit message starts with ‘bump:’, which indicates an automated commit from the previous release. If not, Commitizen determines the necessary version bump based on the commit messages, updates the CHANGELOG.md, and creates a new tag.

Workflow 2: On Tag Creation

This workflow is triggered when a tag is pushed, and it handles the release process:

name: On Tag Creation

on:
  push:
    tags:
      - 'v*'

concurrency:
  group: tag-release-${{ github.ref }}
  cancel-in-progress: true

jobs:
  detect-release-parameters:
    runs-on: ubuntu-latest
    outputs:
      notes: ${{ steps.generate_notes.outputs.notes }}
    steps:
      - name: Setup Python
        uses: actions/setup-python@v5
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Get release notes
        id: generate_notes
        uses: anmarkoulis/commitizen-changelog-reader@v1.2.0
        with:
          tag_name: ${{ github.ref }}
          changelog: CHANGELOG.md

  release:
    runs-on: ubuntu-20.04
    needs: detect-release-parameters
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install poetry
      - name: Configure pypi token
        run: |
          poetry config pypi-token.pypi ${{ secrets.PYPI_TOKEN }}
      - name: Build and publish package
        run: |
          poetry publish --build

  release-github:
    runs-on: ubuntu-latest
    needs: [release, detect-release-parameters]
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
      - name: Create Release Notes File
        run: |
          echo "${{ join(fromJson(needs.detect-release-parameters.outputs.notes).notes, '') }}" > release_notes.txt
      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ github.ref_name }}
        run: |
          gh release create ${{ github.ref }} \
          --title "Release $VERSION" \
          --notes-file "release_notes.txt"

Explanation:

• Trigger: This workflow is triggered by a tag push (e.g., v1.2.0).
• Concurrency: The concurrency setting ensures that only one instance of the workflow runs for each tag, preventing issues like multiple release attempts for the same version.
• detect-release-parameters job: Extracts the changelog notes for the release.
• release job: Builds the package and publishes it to PyPI using Poetry.
• release-github job: Creates a new GitHub release with the generated release notes.

Setting Up the Personal Access Token

To ensure the workflows can perform actions like creating commits and tagging releases, you’ll need to set up a Personal Access Token (PAT) in your GitHub repository:

1. Go to your repository on GitHub.
2. Navigate to Settings > Secrets and variables > Actions.
3. Click on New repository secret.
4. Add a secret with the name PERSONAL_ACCESS_TOKEN and paste your PAT in the value field.

This token is crucial because it allows the workflow to push changes (like the updated changelog and version bump) back to the repository.

Generated CHANGELOG.md Example

After running the workflows, a CHANGELOG.md file will be generated and updated automatically. Here’s an example of what it might look like:

## v2.0.0 (2021-03-31)

### Feat

- **api**: change response of me endpoint

## v1.0.1 (2021-03-30)

### Fix

- **api**: handle null values in the response

## v1.0.0 (2021-03-30)

### Feat

- **parser**: add support for parsing new file formats

This CHANGELOG.md is automatically updated by Commitizen each time a new version is released. It categorizes changes into different sections (e.g., Feat, Fix), making it easy for users and developers to see what's new in each version.

Common Issues and Troubleshooting

Finally, here’s what a GitHub release looks like after being created by the workflow:

• Incorrect Token Permissions: If the workflow fails due to permission errors, ensure that the PAT has the necessary scopes (e.g., repo, workflow).

• Commitizen Parsing Issues: If Commitizen fails to parse commit messages, double-check the commit format and ensure it's consistent with the expected format.

• Bump Commit Conflicts: If conflicts arise when the bump commit tries to merge into the main branch, you might need to manually resolve the conflicts or adjust your workflow to handle them.

• Concurrent Executions: Without proper concurrency control, multiple commits or tags being processed simultaneously can lead to issues like duplicate version bumps or race conditions. This can result in multiple commits with the same version or incomplete releases. To avoid this, we’ve added concurrency settings to both workflows to ensure only one instance runs at a time for each branch or tag.

Conclusion and Next Steps

Automating the release process of your Python library with GitHub Actions and Commitizen not only saves time but also ensures consistency and reduces human errors. With this setup, you can focus more on developing new features and less on the repetitive tasks of managing releases.

As a next step, consider extending your CI/CD pipeline to include automated testing, code quality checks, or even security scans. This would further enhance the robustness of your release process.

Call to Action

If you found this post helpful, please feel free to share it with others who might benefit. I’d love to hear your thoughts or any questions you might have in the comments below. Have you implemented similar workflows in your projects? Share your experiences!

Referenzen und weiterführende Literatur

• Offizielle Website zur semantischen Versionierung
• Commitizen-Dokumentation
• GitHub-Aktionsdokumentation

Das obige ist der detaillierte Inhalt vonAutomatisieren von Python-Bibliotheksversionen mithilfe von GitHub-Aktionen und Commitizen. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!