Première sortie

Ce guide explique comment publier des packages ROS 2 que vous n’avez pas encore publiés. En raison des nombreuses options disponibles lors de la publication des packages ROS, ce guide vise à couvrir le scénario le plus courant et ne couvre pas tous les cas particuliers.

Faire partie d’une équipe de publication

Vous devez faire partie d’une équipe de publication. Si vous ne faites pas encore partie d’une équipe de publication, suivez soit :

Installer les dépendances

Installez les outils que vous utiliserez dans les prochaines étapes en fonction de votre plateforme :

sudo apt install python3-bloom python3-catkin-pkg

Configurer un jeton d’accès personnel

Avertissement

Si le fichier ~/.config/bloom existe sur votre ordinateur, il est probable que vous l’ayez déjà fait auparavant, vous devriez donc ignorer cette section.

Au cours du processus de publication, plusieurs opérations HTTPS Git seront effectuées qui nécessitent une authentification par mot de passe. Pour éviter qu’on vous demande à plusieurs reprises un mot de passe, un Personal Access Token (PAT) sera configuré. Si vous avez configuré l’authentification multifacteur sur votre compte GitHub, vous devez configurer un jeton d’accès personnel.

Créez un jeton d’accès personnel en :

  1. Connectez-vous à GitHub et accédez à Jetons d’accès personnels.

  2. Cliquez sur le bouton Générer un nouveau jeton.

  3. Définissez Remarque sur quelque chose comme Bloom token.

  4. Définissez Expiration sur Aucune expiration.

  5. Cochez les cases public_repo et workflow.

  6. Cliquez sur le bouton Générer un jeton.

Après avoir créé le jeton, vous vous retrouverez sur la page Jetons d’accès personnels. Copiez le jeton alphanumérique surligné en vert.

Enregistrez votre nom d’utilisateur GitHub et votre PAT dans un nouveau fichier appelé ~/.config/bloom, au format ci-dessous :

{
   "github_user": "<your-github-username>",
   "oauth_token": "<token-you-created-for-bloom>"
}

Assurez-vous que les référentiels sont à jour

Sois sûr que:

  • Votre référentiel est hébergé sur une télécommande telle que GitHub.

  • Vous avez un clone du référentiel sur votre ordinateur et vous êtes sur la bonne branche.

  • Le référentiel distant et votre clone sont à jour.

Générer un journal des modifications

Générez un fichier CHANGELOG.rst par package dans votre référentiel à l’aide de la commande suivante :

catkin_generate_changelog --all

Ouvrez tous les fichiers CHANGELOG.rst dans un éditeur. Vous verrez que catkin_generate_changelog a généré automatiquement une section à venir avec des notes de messages de validation :

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Changelog for package your_package
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Forthcoming
-----------
* you can modify this commit message
* and this

Nettoyez la liste des messages de validation pour transmettre de manière concise les changements notables qui ont été apportés aux packages depuis la dernière version, et commettez tous les fichiers CHANGELOG.rst. Ne modifiez pas l’en-tête Forthcoming.

Bump la version du package

Chaque version du package doit avoir un numéro de version unique supérieur à celui de la version précédente. Courir:

catkin_prepare_release

qui effectue les opérations suivantes :

  1. augmente la version du paquet dans package.xml

  2. remplace le titre À venir par version (date) (ex. 0.0.1 (2022-01-08)) dans CHANGELOG.rst

  3. valide ces changements

  4. crée une balise (ex. 0.0.1)

  5. pousse les modifications et la balise vers votre référentiel distant

Note

Par défaut, la version du correctif du paquet est incrémentée, par exemple de 0.0.0 à 0.0.1. Pour incrémenter la version mineure ou majeure à la place, exécutez catkin_prepare_release --bump minor ou catkin_prepare_release --bump major. Pour plus de détails, voir catkin_prepare_release --help.

Libération de la floraison

Exécutez la commande suivante en remplaçant my_repo par le nom de votre dépôt :

bloom-release --new-track --rosdistro rolling --track rolling my_repo

Astuce

  • --new-track indique à bloom de créer un nouveau track et de le configurer.

  • --rosdistro rolling indique que cette version est pour la distribution rolling

  • --track rolling indique que vous voulez que le nom de la piste soit rolling

Vous serez invité à entrer des informations pour configurer une nouvelle piste. Dans un scénario courant tel que :

  • Vos packages se trouvent dans un référentiel appelé my_repo

  • Vous libérez une branche appelée main

  • Le dépôt est hébergé sur GitHub à https://github.com/my_organization/my_repo.git

  • Votre dépôt de version est à https://github.com/ros2-gbp/my_repo-release.git

Vous devez répondre aux invites comme suit :

Configuration

Valeur

Release Repository url

https://github.com/ros2-gbp/my_repo-release.git

Nom du référentiel

mon_dépôt

URI du référentiel en amont

https://github.com/my_organization/my_repo.git

Type VCS en amont

Version

Release Tag

Branche de développement en amont

principal

ROS Distro

Répertoire des correctifs

Release Repository Push URL

Note

Une cellule vide dans le tableau indique que la valeur par défaut doit être utilisée. Répondez simplement à l’invite en appuyant sur Entrée.

Bloom créera automatiquement une pull request pour vous contre rosdistro.

Prochaines étapes

Une fois votre demande de tirage soumise, généralement dans un délai d’un ou deux jours, l’un des responsables de rosdistro examinera et fusionnera votre demande de tirage. Si la construction de votre package réussit, vos packages seront disponibles dans les 24 à 48 heures dans le référentiel ros-testing, où vous pourrez tester vos binaires de pré-version.

Environ toutes les deux à quatre semaines, le gestionnaire de publication de la distribution synchronise manuellement le contenu de ros-testing dans le référentiel ROS principal. C’est à ce moment que vos packages deviennent réellement disponibles pour le reste de la communauté ROS. Pour obtenir des mises à jour sur la date de la prochaine synchronisation (sync), abonnez-vous à la catégorie Packaging and Release Management Category on ROS Discourse.