Publier des modules frontend

La publication des modules frontend est une étape essentielle du processus de développement. Après un seuil raisonnable de commits, ou après un certain temps, vous voudrez probablement publier votre logiciel sur le registre npm afin que les consommateurs puissent l’installer. Ce guide décrit le processus de publication des modules frontend dans l’écosystème O3.

O3 suit actuellement une cadence de publication mensuelle ou bimestrielle. Cela signifie que nous essayons de publier de nouvelles versions de notre frontend dans notre environnement QA environ tous les mois ou tous les deux mois. La revue QA et les retours prennent généralement une semaine, après quoi nous promouvons la version vers notre environnement de démo Production . Cette cadence peut évoluer à mesure que nous acquérons de l’expérience avec ce processus.

Créer une release

Veuillez lire la section Notes importantes à la fin de cette page. Elle couvre quelques étapes du processus de publication qui sont souvent oubliées.

Créer une release O3 comporte généralement deux étapes de publication:

Ouvrir puis fusionner une PR de release qui incrémente les versions locales des packages. Le merge vers main déclenche le job CI pre_release, ou la branche équivalente du workflow de release partagé, et publie une version pre-release taguée next.
Créer une release depuis l’interface GitHub Releases. L’événement release déclenche CI, qui publie le ou les packages sur npm avec le tag latest.

Si vous voulez publier une version de release de votre module, réfléchissez d’abord à quelques éléments, notamment:

Le type de release, c’est-à-dire le type de versionnement sémantique auquel vos changements correspondent. Nos versions suivent la spécification SemVer, avec trois types de release:
- patch - pour les corrections de bugs rétrocompatibles.
- minor - pour les ajouts de fonctionnalités rétrocompatibles.
- major - pour les changements d’API incompatibles.
Par exemple, si la version la plus récente d’un module frontend est v1.0.0:
- Une version patch incrémenterait la version vers 1.0.1.
- Une version minor incrémenterait la version vers 1.1.0.
- Une version major incrémenterait la version vers 2.0.0.

Rédiger un changelog

Avec ces informations, vous pouvez rédiger un changelog. Pour cela:

Allez sur la page releases de votre monorepo et cliquez sur Draft a new release.
Cliquez sur le bouton Choose a tag dans l’interface de la page releases. Choisissez n’importe quel tag, par exemple v1.0.1 pour une release patch si la version la plus récente est v1.0.0. Nous changerons probablement cette valeur après la revue du changelog. Utilisez cette valeur comme titre de release également. Cliquez ensuite sur le bouton Generate release notes.

Nous avons établi une convention dans O3 selon laquelle les titres de PR utilisent l’un de ces formats canoniques:

(type) TICKET: Sentence case summary
(type) Sentence case summary
(BREAKING) TICKET: Sentence case summary
(BREAKING) Sentence case summary

Les valeurs type autorisées entre parenthèses sont (feat), (fix), (chore), (docs), (test) et (BREAKING). Continuez à éviter (refactor), et autorisez les titres de PR sans ticket quand il n’existe pas encore de ticket Jira. Les PR créées par des bots sont exemptées de cette vérification.

Relire le changelog généré avec ces règles de titre en tête devrait vous donner une bonne idée du bump sémantique que la release doit produire. Pour la politique complète des titres de PR et des exemples valides ou invalides, consultez le guide de contribution.

Incrémenter les versions

À ce stade, vérifiez si le dépôt contient un workflow .github/workflows/open-release-pr.yml. Beaucoup de dépôts de modules frontend actuels fournissent une action GitHub Open release PR avec une entrée release_type (patch, minor ou major). Préférez ce workflow quand il existe: il lance la commande de release du dépôt, vérifie le diff de release et ouvre une PR avec le bump de version. Si le dépôt n’a pas ce workflow, ou si vous faites le bump manuellement, utilisez les scripts yarn du dépôt comme décrit ci-dessous.

Monorepos

Pour les monorepos, nous utilisons la commande workspaces pour incrémenter les versions de tous les packages du monorepo. Vous trouverez généralement un script release dans le package.json racine du monorepo qui ressemble à ceci:


"release": "yarn workspaces foreach --all --topological version"

Ce script exécute la commande version sur tous les packages du workspace. Vous devrez ajouter le type de release à cette commande pour déclencher le bump. Par exemple, pour une release major, vous lanceriez:


yarn release major

Cette commande:

Exécute la commande version sur tous les packages du workspace et les incrémente vers une version majeure. Par exemple, si la version courante est 1.0.0, elle devient 2.0.0.
Demande à yarn de trier les packages avant d’exécuter les commandes afin qu’ils passent dans l’ordre topologique, c’est-à-dire que les packages qui dépendent d’autres packages passent plus tard.
Si vous devez éviter de versionner le package.json racine, ajoutez un --exclude explicite pour le nom du package racine.

Non-monorepos

Pour les dépôts qui ne sont pas des monorepos, vous pouvez utiliser directement la commande version. Par exemple, pour incrémenter le package vers une release major, lancez:


yarn version major

Bibliothèques utilisant d’anciennes versions de yarn

Certains de nos projets utilisent des versions anciennes de yarn, comme yarn v1. Le moteur de formulaires Angular en est un exemple. Pour publier le moteur de formulaires Angular, vous lanceriez la commande suivante:


yarn version --new-version <major|minor|patch> --no-git-tag-version

Veillez à suivre les instructions indiquées dans les docs Cutting a release pour éviter les mauvaises surprises.

Étapes après le bump

Une fois le versionnement terminé, vous devriez voir dans votre éditeur un diff contenant un bump de version pour tous les packages du dépôt. Lancez yarn ou yarn install pour mettre à jour votre fichier yarn.lock.

Si le workflow Open release PR du dépôt a créé la branche et le commit pour vous, relisez cette PR puis continuez à partir de là. Si vous faites le bump manuellement, créez une branche de release selon la convention du dépôt, souvent release/vX.X.X ou chore/release-vX.X.X, où X.X.X est le numéro de version publié. Committez le bump avec un titre comme (chore) Release vX.X.X. Voir cet exemple de commit qui incrémente Patient Chart vers v5.0.0.

Une fois le commit de release fusionné dans main, CI publie une version pre-release taguée next sur npm. C’est utile pour les tests anticipés avant de publier latest. Le nom exact du script dépend du dépôt: openmrs-esm-core utilise ci:publish-next, beaucoup de dépôts de modules frontend utilisent ci:prepublish, et certains dépôts passent la commande au workflow partagé release-frontend-module.

Publier sur GitHub

Vous pouvez ensuite retourner dans votre navigateur sur la page releases du dépôt concerné. Relisez les notes de release générées par GitHub, puis mettez à jour le numéro de version et les tags comme il faut.

Les notes de release doivent suivre le format du changelog O3. Ce format comprend un titre, une description et une liste de changements. Les principales catégories sont Features, Bug Fixes, Breaking Changes, Chores, Docs et Tests. Chaque catégorie doit contenir une liste de changements. Il faudra peut-être un peu de travail pour que le changelog corresponde à ce format. Cela en vaut la peine, car cela facilite la revue des changements par le Release Manager et la préparation des notes de release pour la communauté.

Quand tout vous semble correct, cliquez sur le bouton Publish release. Cette étape doit déclencher le workflow CI et, notamment, le job release.

Dans beaucoup de monorepos, ce job exécute un script de publication qui ressemble à ceci:


"ci:publish": "yarn workspaces foreach --all --topological --exclude @openmrs/esm-patient-management npm publish --access public --tag latest"

Les dépôts à package unique peuvent plutôt appeler directement yarn npm publish --access public, et les monorepos excluent souvent le workspace racine de la publication. L’invariant important est le dist-tag npm: l’automatisation de pre-release publie next, tandis qu’une release GitHub publie latest.

Le tag latest correspond à la version que les consommateurs obtiennent par défaut quand ils installent votre module frontend.

Pour voir à quelle version correspond le tag latest d’un module frontend, allez sur sa page npm et cliquez sur le tag version. Cherchez la version la plus récente taguée latest.

Notes importantes

Lors du versionnement du moteur de formulaires Angular , assurez-vous d’incrémenter à la fois la version dans le fichier package.json racine et la version dans le fichier package.json du dossier projects/openmrs-esm-formentry. La bibliothèque réellement publiée vient de ce dossier, il est donc important d’y incrémenter la version aussi. Plus d’informations se trouvent dans cette section du README.
Lors du versionnement de Patient Chart , assurez-vous d’incrémenter la peer dependency Common Lib dans chaque package qui en dépend. Voici un exemple de commit de release qui incrémente à la fois la version du package et la version de la peer dependency: chore: Release v7.0.0 .

Différences propres aux dépôts

Tous les dépôts ne câblent pas les releases de la même manière. Avant de publier, vérifiez:

package.json pour les scripts release, ci:publish, ci:publish-next ou ci:prepublish.
.github/workflows/open-release-pr.yml pour un workflow automatisé de PR de bump de release.
.github/workflows/ci.yml, .github/workflows/node.js.yml ou une référence à un workflow partagé pour voir quels tags sont publiés sur push et sur release.

Suivez toujours les scripts définis dans le dépôt, même si leurs noms diffèrent de ce guide.

Une vérification supplémentaire s’applique aux dépôts du moteur de formulaires Angular (openmrs-ngx-formentry, openmrs-ngx-file-uploader et esm-form-entry-app dans openmrs-esm-patient-chart): avant de publier une release, confirmez que la ligne Angular qu’ils embarquent est toujours prise en charge selon la politique de support des versions Angular.