Automatisation des versions de la bibliothèque Python à l'aide des actions GitHub et de Commitizen

Introduction

Maintenir une bibliothèque Python peut être un défi, surtout lorsqu'il s'agit de publier de nouvelles versions. Le processus peut prendre du temps et être sujet aux erreurs s’il est effectué manuellement. Dans cet article, je vais vous expliquer comment automatiser le processus de publication à l'aide de GitHub Actions et Commitizen. Cette approche garantit que vos versions sont cohérentes, respectent le versioning sémantique (semver) et maintiennent votre journal des modifications à jour, tout en réduisant les interventions manuelles.

Qu’est-ce que le versioning sémantique ?

Le versionnage sémantique (semver) est un schéma de versionnage qui utilise trois nombres au format MAJOR.MINOR.PATCH. Ce schéma fournit un moyen clair et prévisible de communiquer ce qui a changé dans chaque version :

• MAJEUR : modifications avec rupture : tout ce qui n'est pas rétrocompatible.
• MINEUR : Nouvelles fonctionnalités, mais rétrocompatible.
• PATCH : corrections de bugs, entièrement rétrocompatibles.

Le versioning sémantique est crucial car il aide les développeurs à gérer efficacement les dépendances. Lorsque vous savez qu'une nouvelle version d'une bibliothèque n'introduit pas de modifications majeures (par exemple, une mise à jour mineure ou un correctif), vous pouvez mettre à jour vos dépendances en toute confiance sans craindre une panne de votre application.

Pour plus de détails sur Semver, vous pouvez consulter semver.org.

Introduction à l'engagement

Commitizen est un outil qui standardise les messages de validation et automatise la gestion des versions et la création du journal des modifications. En appliquant un format de message de validation spécifique, Commitizen peut déterminer le type de changement de version requis (majeur, mineur ou correctif) et générer automatiquement un journal des modifications.

Le format du message de commit suit cette structure :

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

• Types de validation :
  • feat : Indique une nouvelle fonctionnalité. Cela peut entraîner une modification mineure de la version. Si un commit inclut une note BREAKING CHANGE, cela entraîne une modification majeure de la version.
  • fix : indique une correction de bug et entraîne une modification de la version du correctif.
  • chore, ci et autres : ceux-ci ne déclenchent pas de changement de version.

Par exemple :

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

Dans cet exemple, la note BREAKING CHANGE dans un commit d'exploit déclencherait un changement de version majeur. Cette cohérence garantit que vos numéros de version communiquent le bon niveau de changement, ce qui est essentiel pour les utilisateurs qui comptent sur votre bibliothèque.

Configuration de la validation

Pour intégrer Commitizen à votre projet Python, vous devez le configurer dans votre fichier pyproject.toml. Vous trouverez ci-dessous la configuration que vous devrez ajouter :

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

Explication :

• name : Spécifie la convention de message de validation à utiliser. Nous utilisons le format de commits conventionnel.
• version : La version actuelle de votre projet. Vous devriez commencer par "0.1.0" ou quelle que soit votre version initiale.
• tag_format : définit la façon dont les balises sont formatées, v$version étant le format typique (v1.0.0, v1.1.0, etc.).
• version_files : répertorie les fichiers dans lesquels les numéros de version sont suivis. Cette configuration garantit que le numéro de version dans pyproject.toml est mis à jour automatiquement.
• update_changelog_on_bump : met automatiquement à jour le fichier CHANGELOG.md chaque fois qu'un changement de version se produit.

Pourquoi automatiser le processus de publication ?

La gestion manuelle des versions peut être fastidieuse et sujette aux erreurs, surtout à mesure que votre projet se développe. L'automatisation apporte plusieurs avantages clés :

• Cohérence : garantit que les changements de version et les journaux de modifications sont traités de la même manière à chaque fois.
• Efficacité : permet de gagner du temps en réduisant les étapes manuelles impliquées dans la publication d'une nouvelle version.
• Précision : minimise les erreurs humaines, telles que l'oubli de mettre à jour le journal des modifications ou la modification incorrecte de la version.

Présentation : le processus de publication automatisé

Pour vous donner une idée claire du fonctionnement de l'automatisation, voici un aperçu général :

1. Lors de la fusion vers la branche principale : lorsqu'une pull request (PR) est fusionnée dans la branche principale, le workflow vérifie les messages de validation, décide si une modification de version est nécessaire, met à jour le journal des modifications et marque la version si nécessaire .
2. Lors de la création d'une balise : Lorsqu'une balise est poussée (indiquant une nouvelle version), le workflow publie la nouvelle version sur PyPI et crée une version GitHub avec le journal des modifications correspondant.

Fractionner le flux de travail : événements de fusion ou de balise

Pour plus de simplicité et de clarté, nous diviserons l'automatisation en deux flux de travail :

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!

Références et lectures complémentaires

• Site officiel du versionnage sémantique
• Documentation engagée
• Documentation des actions GitHub

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!