Guide du responsable du paquet ROS 2
Chaque paquet du noyau ROS 2 a un ou plusieurs mainteneurs qui sont responsables de la santé générale du paquet. Ce guide donne des informations sur les responsabilités d’un mainteneur de paquet de base ROS 2.
Table des matières
Commentaires
Tout le code entrant dans les référentiels principaux de ROS 2 doit être examiné. La revue recherche :
Convenance dans le paquet
Code correct
Conforme aux directives du développeur :
Ajoute des tests pour le bogue/fonctionnalité
Ajoute de la documentation pour les nouvelles fonctionnalités
Nettoyer l’exécution de l’intégration continue
Cible la branche par défaut (généralement « rolling »)
A au moins une approbation d’un mainteneur qui n’est pas l’auteur
Intégration continue
Tout le code entrant dans les référentiels principaux de ROS 2 doit être exécuté via l’intégration continue. ROS 2 dispose actuellement de deux systèmes CI distincts, et il est nécessaire que les PR réussissent les deux avant de fusionner.
Versions PR (https://build.ros2.org/view/Rpr)
Les builds ROS 2 PR (Pull Request) s’exécutent automatiquement chaque fois qu’une pull request est ouverte. Ces builds exécutent une build et un test de ce package, et de ce package uniquement. Cela signifie qu’il ne construit aucune dépendance et qu’il ne construit aucun paquet qui dépend de ce paquet. Ces versions sont bonnes pour un retour rapide pour voir si le changement passe les linters, les tests unitaires, etc. Il y a deux problèmes majeurs avec eux :
Ces versions ne fonctionnent pas sur plusieurs référentiels (elles ne fonctionneront donc pas pour ajouter ou modifier une API, etc.)
Ces tests ne fonctionnent que sur Linux (ils ne fonctionneront pas sur macOS ou Windows)
Pour résoudre ces deux problèmes, il existe également les builds CI.
Versions CI (https://ci.ros2.org)
Les builds de CI ne s’exécutent pas automatiquement lorsqu’une demande d’extraction est ouverte. L’un des mainteneurs du paquet doit demander manuellement qu’une construction CI soit effectuée en allant sur https://ci.ros2.org/job/ci_launcher/ .
Par défaut, exécuter une tâche de cette manière générera et exécutera des tests pour tous les packages (> 300 actuellement) sur toutes les plates-formes (Linux, macOS et Windows). Comme une exécution complète peut prendre plusieurs heures et immobiliser les machines CI, il est recommandé que toutes les exécutions ici limitent le nombre de packages construits et testés. Ceci peut être accompli en utilisant les arguments colcon --packages-up-to, --packages-select, --packages-above-and-dependencies, --packages -above, entre autres. Voir la documentation colcon pour plus d’exemples sur les drapeaux qui peuvent être utilisés. Une documentation supplémentaire sur l’utilisation des machines CI est disponible sur https://github.com/ros2/ci/blob/master/CI_BUILDERS.md.
Fusionner les demandes d’extraction
Une demande d’extraction peut être fusionnée si toutes les conditions suivantes sont remplies :
Le bot DCO signale un résultat positif
La version PR rapporte un résultat satisfaisant
La version CI signale un résultat satisfaisant sur toutes les plates-formes
Le code a été revu et approuvé par au moins un mainteneur
Une fois qu’un PR est fusionné, il sera automatiquement construit avec les prochains nightlies. Il est fortement recommandé de vérifier les nightlies après la fusion des pull requests pour s’assurer qu’aucune régression ne s’est produite.
Garder le CI vert
Les tâches nocturnes qui exécutent des tests sont généralement beaucoup plus complètes que ce qui est fait pour les demandes d’extraction individuelles. Pour cette raison, il peut y avoir des régressions qui se produisent dans les nightlies qui n’ont pas été observées dans les emplois CI. C’est la responsabilité des mainteneurs de paquets de vérifier les régressions dans leurs paquets aux emplacements suivants :
Pour tout problème détecté, de nouveaux problèmes et/ou demandes d’extraction sur les référentiels concernés doivent être ouverts.
Faire des communiqués
Afin d’obtenir de nouvelles fonctionnalités et des corrections de bogues pour les utilisateurs finaux, les responsables du paquet doivent périodiquement faire une version du paquet (une version peut également être demandée à la demande par d’autres responsables).
Comme indiqué dans le guide du développeur, les packages ROS 2 suivent semver pour les numéros de version.
Une version en termes ROS se compose de deux étapes distinctes : créer une version source, puis créer une version binaire.
Version source
Une version source crée un journal des modifications et une balise dans le référentiel concerné.
Le processus commence par générer ou mettre à jour les fichiers CHANGELOG.rst avec la commande suivante :
$ catkin_generate_changelog
Si un ou plusieurs packages du référentiel ne contiennent pas CHANGELOG.rst, ajoutez l’option --all pour remplir tous les commits précédents pour chaque package. La commande catkin_generate_changelog remplira simplement les fichiers avec les journaux de validation du référentiel. Étant donné que ces journaux de validation ne sont pas toujours appropriés pour un journal des modifications, il est recommandé de modifier CHANGELOG.rst et de le modifier pour le rendre plus lisible. Une fois la modification effectuée, il est important de valider le fichier CHANGELOG.rst mis à jour dans le référentiel.
L’étape suivante consiste à remonter la version dans le package.xml et les fichiers changelog avec la commande suivante :
$ catkin_prepare_release
Cette commande trouvera tous les packages dans le référentiel, vérifiera que les journaux des modifications existent, vérifiera qu’il n’y a pas de modifications locales non validées, incrémentera la version dans les fichiers package.xml et validera/marquera les modifications avec une balise compatible bloom. L’utilisation de cette commande est le meilleur moyen de s’assurer que les versions de publication sont cohérentes et compatibles avec bloom. Par défaut, catkin_prepare_release remplacera la version corrigée des packages, par ex. 0.1.1 -> 0.1.2 . Cependant, il peut également remplacer le numéro mineur ou majeur, ou même avoir un ensemble de versions exactes. Voir la sortie d’aide de catkin_prepare_release pour plus d’informations.
En supposant que ce qui précède a réussi, une version source a été créée.
Version binaire
L’étape suivante consiste à utiliser la commande bloom-release pour créer une version binaire. Pour des instructions complètes sur l’utilisation de bloom, veuillez consulter http://wiki.ros.org/bloom. Pour faire une version binaire d’un paquet, exécutez :
$ bloom-release --track <rosdistro> --rosdistro <rosdistro> <repository_name>
Par exemple, pour publier le référentiel rclcpp dans la distribution Rolling, la commande serait :
$ bloom-release --track rolling --rosdistro rolling rclcpp
Cette commande récupère le référentiel de version, apporte les modifications nécessaires pour effectuer la version, envoie les modifications au référentiel de version et enfin ouvre une demande d’extraction sur https://github.com/ros/rosdistro .
Rétroportage vers les distributions publiées
Toutes les modifications entrantes doivent d’abord atterrir sur la branche de développement. Une fois qu’un changement a été fusionné dans la branche de développement, il peut être envisagé de le rétroporter vers les distributions publiées. Cependant, tout code rétroporté ne doit pas casser API ou ABI dans une version publiée Distribution. Si une modification peut être rétroportée sans casser l’API ou l’ABI, une nouvelle demande d’extraction ciblant la branche appropriée doit être créée. La nouvelle demande d’extraction doit être ajoutée au tableau de projet des distributions appropriées à l’adresse https://github.com/orgs/ros2/projects. La nouvelle pull request doit avoir toutes les étapes exécutées comme avant, mais en veillant à cibler la distribution en question pour CI, etc.
Répondre aux problèmes
Les mainteneurs de paquets doivent également examiner les problèmes entrants sur le référentiel et trier les problèmes rencontrés par les utilisateurs.
Pour les problèmes qui ressemblent à des questions, le problème doit être fermé et l’utilisateur redirigé vers https://answers.ros.org.
Si un problème ressemble à un problème, mais n’est pas pertinent pour ce référentiel particulier, il doit être déplacé vers le référentiel approprié avec le bouton GitHub « Transférer le problème ».
Si le déclarant n’a pas fourni suffisamment d’informations pour déterminer la cause du problème, il doit lui demander plus d’informations.
S’il s’agit d’une nouvelle fonctionnalité, marquez le problème avec « help-wanted ».
Tous les problèmes restants doivent être reproduits et déterminés s’il s’agit vraiment d’un bogue. S’il s’agit d’un bogue, les correctifs sont très appréciés.
Obtenir de l’aide
Lors de la maintenance d’un package, des questions sur les procédures générales ou des problèmes individuels peuvent survenir.
Pour les questions générales, veuillez suivre les consignes de contribution.
Pour des questions sur des problèmes individuels, veuillez étiqueter l’équipe ROS 2 GitHub (@ros/team), et un membre de l’équipe y jettera un coup d’œil.