Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Création de version et packaging

CMAP/CNRS/Ecole polytechnique

Nous voici dans la dernière partie de cet atelier. Nous souhaitons à présent pouvoir déclencher un événement à la main qui

Jusqu’à présent, nous n’avons pas fait attention si le nom de la pull request satisfaisait aux critères du commit conventionnel. Hors, cela devient ici indispensable pour que le CHANGELOG soit généré correctement et automatiquement. Nous allons donc commencer par mettre une action en place qui vérifie que le titre de la pull request suit la nomenclature du commit conventionnel.

Première version

Afin d’automatiser le processus de création de version de manière automatique, nous devons l’initier. Pour cela, nous allons créer un fichier version.txt à la racine du projet avec le contenu suivant

0.0.1

Une fois que cette modification est fusionnée dans la branche principale, il suffit de créer une première version du projet avec le même numéro de version.

Allez sur votre dépôt GitHub et cliquez sur Release qui se trouve dans la colonne de droite. Puis Create a new release.

Allez dans Choose a tag et rentrez v0.0.1. Et enfin Publish release.

En retournant sur la page d’accueil de votre dépôt, vous devriez voir apparaître en dessous de Release votre v0.0.1.

Vérification du titre de la pull request

Nous allons à présent vérifier le titre de la pull request. Tout se passe encore une fois dans la section on qui gère les événements. Nous allons à présent utiliser l’événement pull_request_target qui intervient à chaque fois qu’une opération est demandée sur l’interface de la pull request.

Nous allons sélectionner trois types d’activités

Nous utiliserons l’action semantic-pull-request pour la validation.

Créez l’action associée, testez et fusionnez dans la branche principale.

Création automatique d’une nouvelle version

À présent, à partir des titres de la pull request, nous allons pouvoir déterminer les versions successives en utilisant la gestion sémantique de version semver. Nous n’allons pas rentrer dans les détails, mais donner juste assez d’éléments pour la compréhension de la suite. Un numéro de version peut être décomposé comme suit

La version corrective correspond à une correction qui corrige un comportement interne incorrect, mais qui ne casse pas l’API actuelle. La version mineure correspond à l’ajout de nouvelles fonctionnalités qui ne cassent pas l’API actuelle. Enfin, la version majeure correspond à des changements qui cassent l’API actuelle.

Généralement, lorsque la version majeure est supérieure ou égale à 1, le logiciel sort d’un état de développement pour aller vers un état dit stable. Notre projet est un problème jouet et ne peut être considéré comme un logiciel dans un état stable. Nous garderons donc la version majeure à 0. Par conséquent, si la version mineure est augmentée, cela signifie que des nouvelles fonctionnalités ont été ajoutées et que celles-ci peuvent casser ou non l’API actuelle.

Revenons aux commits conventionnels et à leur influence sur la montée de version.

Comment générer ce modèle de manière automatique sur notre dépôt ? En utilisant GitHub Actions !

Nous allons utiliser cette action : release-please-action qui utilise release-please.

release-please a besoin de fichiers de configuration pour contrôler son comportement. Voici les deux fichiers à ajouter à la racine du dépôt : vous les trouverez dans le répertoire material/6.packaging/required_files.

release-please-config.json
{
    "release-type": "simple",
    "include-component-in-tag": false,
    "include-v-in-tag": true,
    "changelog-path": "CHANGELOG.md",
    "bump-minor-pre-major": true,
    "packages": {
        ".": {}
    }
}
.release-please-manifest.json
{
    ".": "0.0.1"
}

La clé packages indique que le projet à publier se trouve à la racine du dépôt (.). Ne l’oubliez pas : sans elle, release-please ne trouve rien à publier et se termine sans afficher d’erreur.

Cette action se joue en deux temps.

Créez l’action associée et ajoutez les fichiers de configuration à votre dépôt. Vous pouvez fusionner à la branche principale.

D’ici, vous devriez avoir deux commits depuis la dernière version et ceux-ci devraient suivre la nomenclature des commits conventionnels. Vous pouvez donc tester la création d’une nouvelle version !

Vous pouvez également tester en faisant des pull request qui mixent des fix et des feat et voir le comportement.

Packaging conda

Nous allons montrer dans cette section comment déclencher la construction d’un paquet conda lorsqu’une nouvelle version est disponible, et comment le rendre directement accessible sur votre channel conda.

Construction locale

La construction d’un paquet conda se fait à partir d’une recette. Copiez le répertoire material/6.packaging/required_files/recipe à la racine de votre dépôt. Il contient

recipe.yaml
context:
  version: ${{ env.get("VERSION") }}

package:
  name: splinart-cpp
  version: ${{ version }}

source:
  path: ..

build:
  number: 0

requirements:
  build:
    - ${{ compiler("cxx") }}
    - cmake
    - ninja
  host:
    - xtensor >=0.27,<0.28
    - libopencv
    - cli11

tests:
  - script:
      - splinart-cpp --help

about:
  homepage: https://github.com/gouarin/splinart-cpp
  license: BSD-3-Clause
  license_file: LICENSE
  summary: Generative art with circles and splines

Quelques remarques sur cette recette

Nous construisons le paquet avec rattler-build. Nous ne l’ajoutons pas à l’environnement du projet : rattler-build y amènerait des versions plus récentes de certaines bibliothèques (comme libcxx sous macOS) qui ne fonctionnent plus avec le compilateur du projet. La commande pixi exec lance un outil dans un environnement temporaire, séparé de celui du projet.

Lancez la construction

Linux & macOS
Windows
VERSION=$(cat version.txt) pixi exec rattler-build build --recipe recipe --output-dir output

Si tout s’est bien passé, le paquet se trouve dans le répertoire output, dans un sous-répertoire qui porte le nom de votre plateforme (par exemple output/linux-64/splinart-cpp-0.0.1-h....conda). Ajoutez output à votre fichier .gitignore.

Nous allons essayer d’installer ce paquet avec pixi. Le répertoire output est un channel conda local. Créez un projet de test en dehors de votre dépôt, ajoutez-lui ce channel en premier, puis installez le paquet

pixi init test-splinart
cd test-splinart
pixi workspace channel add --prepend file:///chemin/vers/splinart-cpp/output
pixi add splinart-cpp
pixi run splinart-cpp

Une fenêtre doit s’ouvrir avec un cercle.

Anaconda

Nous allons maintenant mettre le paquet construit localement sur anaconda.org pour être sûr que tout le processus fonctionne avant de l’automatiser. Vous devez donc vous créer un compte : son nom sera celui de votre channel.

Pour déposer un paquet, que ce soit depuis votre machine ou depuis une action, il faut s’authentifier avec un token. Une fois le compte créé, cliquez sur votre avatar et choisissez Settings. Allez ensuite dans Access et créez un token qui a les droits suivants

Vous pouvez maintenant déposer le paquet sur votre compte

Linux & macOS
Windows
ANACONDA_API_KEY=votre_token pixi exec rattler-build upload anaconda --owner votre_compte output/*/splinart-cpp-*.conda

Si tout s’est bien passé, vous devriez voir votre paquet sur votre compte anaconda. Pour tester l’installation, retournez dans le projet test-splinart, remplacez le channel local par le vôtre et réinstallez le paquet

pixi workspace channel remove file:///chemin/vers/splinart-cpp/output
pixi workspace channel add --prepend votre_compte
pixi add splinart-cpp

Construction et déploiement du paquet conda

Maintenant que nous avons vérifié que tout se passe bien localement, nous allons ajouter une action qui construit le paquet sur Linux, macOS et Windows, et qui le dépose sur votre compte anaconda lorsqu’une nouvelle version est publiée.

Il y a ici deux ingrédients

Voici à quoi ressemble l’action. Elle se trouve aussi dans le répertoire material/6.packaging/required_files/.github/workflows.

conda.yml
name: Publish on conda

on:
    pull_request:
    release:
        types: [published]
    workflow_dispatch:

jobs:
    build:
        runs-on: ${{ matrix.os }}
        strategy:
            fail-fast: false
            matrix:
                os:
                    - ubuntu-latest
                    - macos-15-intel
                    - macos-latest
                    - windows-latest
        steps:
            - uses: actions/checkout@v7

            - uses: prefix-dev/setup-pixi@v0.11.3
              with:
                  pixi-version: v0.84.1
                  run-install: false

            - name: Read the version
              shell: bash
              run: echo "VERSION=$(cat version.txt)" >> "$GITHUB_ENV"

            - name: Build the package
              run: pixi exec rattler-build build --recipe recipe --output-dir output

            - name: Upload on anaconda.org
              if: github.event_name == 'release'
              shell: bash
              env:
                  ANACONDA_API_KEY: ${{ secrets.ANACONDA_TOKEN }}
              run: pixi exec rattler-build upload anaconda --owner votre_compte output/*/splinart-cpp-*.conda

.github/workflows/conda.yml

Plusieurs remarques

Si la pull request arrive à construire le paquet conda, vous pouvez fusionner cette branche dans la branche principale.

Testez cette action en créant au préalable une nouvelle version : c’est-à-dire en exécutant deux fois l’action release-please (une fois pour créer une pull request avec le changelog et la montée de version et une deuxième fois pour créer le tag et l’archive).