Contribuer

Si vous souhaitez contribuer à O3, voici les étapes à suivre.

Demandez l’accès à OpenMRS Jira . Si vous n’avez pas encore accès, ouvrez une demande auprès du Help desk . Attendez au moins 24 heures pour l’approbation. Vous recevrez un e-mail une fois la demande approuvée. Ensuite, consultez les tickets O3 ouverts . Les bons premiers tickets portent le label intro .
Rejoignez notre canal Slack et présentez-vous. Vous devrez d’abord créer un compte Slack OpenMRS si vous n’en avez pas.
Une fois votre environnement prêt, vous pouvez commencer à contribuer à O3. Commencez par lire les conventions de code et le guide de développement des modules frontend pour comprendre ce que nous attendons des contributeurs. Lisez aussi les dépôts clés pour comprendre la base de code et la façon dont les différentes parties s’assemblent.
Si un domaine particulier vous intéresse, envisagez de rejoindre la feature squad correspondante. Chez OpenMRS, les feature squads permettent d’organiser le travail des différentes équipes. Elles sont un bon moyen de rencontrer les personnes du projet et de comprendre comment les différentes parties du système s’articulent.
Restez positif. Nous sommes une communauté accueillante et nous aimons nous entraider. Si vous voyez quelqu’un en difficulté, aidez si vous le pouvez. Si vous hésitez sur quelque chose, demandez sur le canal Slack #openmrs3-helpme.

Environnements de déploiement

La communauté O3 maintient trois environnements hébergés. Comprendre ce que chacun exécute vous aide à savoir où vérifier votre travail et où signaler les bugs.

Environnement	URL	Ce qu’il exécute	Tag npm	Mis à jour quand
dev3	dev3.openmrs.org	Derniers builds de la branche `main`	`next`	Automatiquement à chaque merge vers `main`
test3	test3.openmrs.org	Release candidates	`latest`	Cycle de release mensuel ou bimestriel
o3	o3.openmrs.org	Release de production stable	`latest`	Après la revue QA de test3

Ces environnements sont construits depuis le dépôt openmrs-distro-referenceapplication , qui définit l’ensemble exact des modules frontend et leurs versions dans son fichier spa-assemble-config.json. Sur la branche main, chaque module pointe vers le tag npm next. C’est ce que dev3 exécute. Lorsqu’une release est créée, par exemple 3.6.0-rc.5, cette configuration bascule tous les modules vers le tag npm latest, qui est ce que test3 et o3 exécutent. Le tag next est publié automatiquement par CI quand une PR est fusionnée dans main dans n’importe quel dépôt de module frontend. Le tag latest est publié quand une release est créée.

Pour signaler des bugs, utilisez dev3 comme référence. C’est l’environnement le plus proche du tableau Jira et il reflète l’état le plus récent du code. Si un bug existe sur dev3, ouvrez un ticket. Si un bug existe sur o3 ou test3 mais pas sur dev3, il est probablement déjà corrigé dans main. Vérifiez les PR récentes avant d’ouvrir un ticket. À l’inverse, si un bug existe sur dev3 mais pas sur o3 ou test3, c’est une régression introduite après la dernière release.

Directives de contribution

Tickets

Nous utilisons Jira pour suivre les tickets et le travail. Si vous prévoyez de contribuer à O3, vous devez connaître notre façon d’utiliser Jira. Voici quelques recommandations pour créer et traiter des tickets:

Nous recommandons généralement d’ouvrir un ticket sur notre tableau d’issues avant de commencer une fonctionnalité ou une correction de bug. Cela nous aide à vérifier que le travail est nécessaire et qu’il n’est pas déjà en cours. Dans beaucoup de cas, le ticket permet aussi de comprendre le contexte du travail et le problème à résoudre. C’est également précieux pour l’historique et pour les futurs contributeurs. Parcourez les tickets existants pour voir s’il existe déjà un ticket pour le travail envisagé. S’il n’y en a pas, créez-en un. En cas de doute, demandez sur le canal Slack #openmrs3-helpme.
Quand vous créez un ticket, donnez-lui un titre et une description clairs. La description doit inclure le problème à résoudre, le contexte et toute information utile à la compréhension du travail proposé. S’il existe des fichiers de design ou des maquettes, joignez-les. Si le ticket concerne un bug, ajoutez les étapes de reproduction. Si possible, ajoutez des captures d’écran ou des vidéos. Plus vous fournissez d’informations, plus il sera facile de comprendre le travail proposé. En cas de doute, consultez les bonnes pratiques Jira pour rédiger des tickets utiles.
Vous n’êtes pas obligé de vous assigner le ticket quand vous le créez. Si vous n’avez pas la bande passante pour le traiter, laissez-le non assigné. Si vous pouvez le prendre, assignez-le-vous. En général, il vaut mieux le laisser non assigné si vous n’êtes pas sûr de pouvoir travailler dessus rapidement. Ainsi, quelqu’un d’autre pourra le prendre. Si vous vous êtes assigné un ticket et que vous ne pouvez plus le traiter, désassignez-vous pour qu’une autre personne puisse le prendre.
Ne désassignez pas un ticket d’une autre personne sans en discuter avec elle. Si vous pensez que quelqu’un d’autre devrait traiter un ticket, demandez-lui d’abord si elle peut le prendre. Si ce n’est pas possible, elle se désassignera. Une bonne communication est essentielle.

Pull requests

L’étape suivante consiste à créer une pull request (PR) avec vos changements. Nous utilisons les PR pour relire et fusionner le code dans les branches principales de nos dépôts. Toute personne peut ouvrir une PR. Le même processus s’applique à tous les contributeurs, qu’il s’agisse d’une première contribution ou d’un membre de l’équipe core.

Voici quelques recommandations pour créer une PR:

Forker et cloner le dépôt - Avant de créer une PR, vous devez forker le dépôt auquel vous voulez contribuer. Une fois le fork créé, clonez-le sur votre machine. Lisez les instructions de setup dans le README du dépôt.
Créer une branche dans Git pour isoler votre travail de la branche principale. Le nom de branche doit décrire le travail. Par exemple, pour corriger un bug, utilisez une branche comme fix/bug-description. Pour ajouter une fonctionnalité, utilisez feat/feature-description. Si vous n’êtes pas sûr du type de changement, demandez sur #openmrs3-helpme.
Une fois vos changements prêts à pousser, ajoutez-les et créez un commit. Le message de commit doit être bref et descriptif. Nous utilisons couramment les labels de conventional commits . Les plus fréquents sont BREAKING, feat, fix, chore, docs et test. Voici des exemples:
- BREAKING: Replace the public orders API contract
- feat: Add search bar to medications widget
- fix: Console error when visiting allergies page
- chore: Update dependencies
- docs: Clarify local setup steps
- test: Add unit tests for medications widget

Si vous pouvez fournir un message de commit plus détaillé, c’est encore mieux. Plus vous donnez de contexte, plus il sera facile de comprendre le travail proposé.

Incluez des tests quand c’est possible. Les modules React actuels utilisent généralement Vitest, React Testing Library et Playwright; des dépôts plus anciens peuvent encore utiliser Jest. Les tests améliorent la qualité du code et aident à éviter les régressions. Si vous ne savez pas comment écrire des tests, demandez sur #openmrs3-helpme.
Créer un commit déclenchera le linter et le formatter. S’il y a des erreurs de lint, corrigez-les avant de pousser. Dans beaucoup de cas, un outil d’extraction des clés et chaînes de traduction sera également lancé. Si de nouvelles clés sont trouvées, committez les changements générés dans les fichiers de traduction avec le code qui les introduit. C’est important pour notre processus i18n. Assurez-vous de committer les changements de lint et d’i18n avant de pousser.
Pour ouvrir vos changements en PR, poussez votre branche vers votre fork. Avant le push, un script vérifiera généralement que le code est formaté, que le lint passe, que les tests passent et qu’il n’y a pas d’erreurs de type. Si un problème survient, corrigez-le puis poussez à nouveau. Une fois la branche poussée, créez une PR depuis l’interface GitHub . La PR doit cibler la branche principale du dépôt auquel vous contribuez.
La plupart des dépôts ont un modèle de PR à remplir. Il demande des informations sur le travail, le contexte et d’autres détails utiles. Lisez et remplissez le modèle de PR. Il existe pour nous donner les informations nécessaires dans un format facile à relire. Le remplir correctement rend le travail de tout le monde plus rapide et plus simple.
Le titre de votre PR doit utiliser l’un des formats canoniques suivants:
- (type) TICKET: Sentence case summary lorsqu’il existe un ticket Jira
- (type) Sentence case summary lorsqu’il n’existe pas encore de ticket Jira
- (BREAKING) TICKET: Sentence case summary lorsqu’un changement incompatible a un ticket Jira
- (BREAKING) Sentence case summary lorsqu’un changement incompatible n’a pas encore de ticket Jira
Les valeurs type autorisées entre parenthèses sont feat, fix, chore, docs et test. Utilisez (BREAKING) pour un changement incompatible pour les consommateurs downstream, et n’utilisez pas (refactor) dans les titres de PR. Les PR sans ticket sont acceptées quand aucun ticket Jira n’existe encore. Si un ticket est créé plus tard, mettez à jour le titre de la PR et la section Related Issue. Les PR créées par des bots sont exemptées de cette règle.

Pour choisir le bon label:
- Utilisez (BREAKING) lorsqu’un consommateur downstream doit modifier son code pour s’adapter.
- Utilisez (feat) pour la plupart des changements fonctionnels ou visibles par les utilisateurs. Ce devrait être le label le plus courant pour le travail produit normal.
- Utilisez (fix) seulement pour les petites corrections de bugs et cas limites qui corrigent un comportement sans introduire de changement fonctionnel plus large.
- Utilisez (chore) pour les travaux d’infrastructure comme la configuration, la CI, les dépendances ou la maintenance. Une PR (chore) ne doit pas changer le comportement runtime, sauf indirectement via le build ou la configuration d’outillage.
- Utilisez (docs) pour les changements de documentation uniquement.
- Utilisez (test) pour les changements de tests uniquement.
Exemples valides:
- (fix) O3-2657: Show inline errors when saving orders fails
- (feat) O3-2724: Move overlays into the framework
- (BREAKING) O3-9000: Replace the public orders API contract
- (docs) Fix README examples
Exemples invalides:
- fix: Show inline errors when saving orders fails
- O3-2657: Show inline errors when saving orders fails
- (feat)O3-2657: Show inline errors when saving orders fails
- (refactor) Tidy the workspaces implementation
Nous utilisons ces labels pour déterminer les bumps de version lors de la publication des modules frontend. Les changelogs que nous publions avec chaque release sont générés à partir des titres de PR. Il est donc important de suivre cette convention. Ne vous inquiétez pas si vous hésitez sur le bon label. Votre reviewer vous aidera à choisir.
Pousser des commits supplémentaires - Les pull requests peuvent, et devraient souvent, contenir plusieurs commits. Ces commits sont squashés quand la PR est fusionnée dans main.
Ne fermez pas une PR pour en recréer une avec le même code - Si vous avez ouvert une PR et qu’un reviewer a demandé des changements, ne créez pas une nouvelle PR avec les mises à jour en fermant l’ancienne. Cela complique fortement le travail des reviewers.
Inclure des captures d’écran ou vidéos - Si votre PR inclut des changements visuels, ajoutez des captures ou vidéos dans la description. Cela aide les reviewers à comprendre vos changements. Si vous ne savez pas comment faire, demandez sur #openmrs3-helpme.
Ajouter un lien vers le ticket Jira - Si votre PR est liée à un ticket Jira, ajoutez le lien dans la section Related issue du modèle. Cela nous aide à suivre le travail et à comprendre son contexte.
Fournir autant de contexte que possible - Plus vous donnez de contexte, plus il est facile pour les reviewers de comprendre le travail. Voici des informations utiles:
- Le problème que vous essayez de résoudre
- Le contexte du travail
- Le comportement actuel et le comportement attendu
- Toute information pertinente pour comprendre les changements
- Des fichiers de design ou maquettes
- Les étapes de reproduction si la PR corrige un bug
- Des captures d’écran ou vidéos si la PR inclut des changements visuels
Voici un exemple de PR bien documentée.
Travailler par incréments - Les petites PR sont plus faciles à lire et à valider. Ouvrir plusieurs PR pour un même ticket est une excellente approche si elles représentent des morceaux ou étapes distinctes du travail.
Ne pas augmenter le scope d’une PR après revue - Si votre code a été relu, n’ajoutez pas beaucoup de code non lié à la revue. Les fixups sont acceptables, mais les nouvelles fonctionnalités doivent avoir leurs propres PR. Les petites PR sont plus simples à relire.
Votre première PR dans une base de code doit être petite - Prenez le temps de comprendre ce que le reviewer attend avant de soumettre une PR très volumineuse.
Mettre la PR en Draft si elle est encore en cours. C’est un bon signal pour indiquer que vous n’êtes pas prêt pour une revue complète. Les Draft PR peuvent être utiles pour obtenir des retours tôt.
Il est de votre responsabilité, en tant qu’auteur de PR, de vous assurer que tous les checks automatisés passent avant de demander une revue. La plupart des dépôts ont une GitHub Action qui exécute ces checks automatiquement. Si des checks échouent, corrigez les problèmes avant de demander une revue. Si vous avez besoin d’aide, demandez sur #openmrs3-helpme.

Revue de code

Une fois la PR ouverte, l’étape suivante est la revue. Les revues de code sont essentielles au processus de développement. Elles aident à garantir que le code proposé est de bonne qualité et qu’il respecte les standards du projet. Bien menées, elles élèvent le niveau de qualité du projet et permettent à chacun d’apprendre des autres.

En général, les reviewers devraient tendre vers l’approbation d’une PR dès lors qu’elle améliore clairement la santé générale du système concerné, même si elle n’est pas parfaite.

Motivation des revues de code

Qualité - Les revues de code aident à vérifier que le code proposé est de bonne qualité. Elles permettent de repérer des bugs, d’améliorer les performances et de s’assurer que le code est maintenable et scalable.
Apprentissage - Les revues de code sont une occasion d’apprendre. Elles vous aident à progresser, à mieux connaître la base de code et à découvrir de bonnes pratiques. Les interactions positives entre reviewers et auteurs renforcent aussi les liens sociaux et le sentiment de communauté.
Cohérence - Les revues de code aident à garantir que le code proposé est cohérent avec le reste de la base de code. Elles vérifient que le code suit les conventions du projet et qu’il est facile à lire.
Lisibilité - Il est difficile d’évaluer soi-même la lisibilité de son travail. Les revues de code aident à vérifier que le code est facile à lire et à comprendre. Un code lisible est plus facile à maintenir et à déboguer.
Détection des erreurs accidentelles et structurelles - Les revues de code aident à repérer les erreurs accidentelles, comme les fautes de frappe, mais aussi les erreurs structurelles, comme les problèmes de logique ou de performance.

Voici quelques recommandations générales pour participer aux revues de code:

Relire le code des autres - Les revues de code vont dans les deux sens. Si vous voulez que votre code soit relu, soyez prêt à relire celui des autres. Cela aide à maintenir la qualité globale du projet.
Être respectueux - Les revues peuvent être sensibles. Soyez respectueux et constructif. Le but est d’aider l’auteur à améliorer son code, pas de le critiquer. Les revues sont une occasion d’apprentissage pour tout le monde.
Être précis - Quand vous donnez un retour, soyez précis sur ce qui vous plaît ou non. Si vous avez une suggestion, expliquez clairement quoi changer et pourquoi. Plus votre retour est précis, plus il est facile à comprendre et à appliquer. Les liens vers de la documentation ou des exemples sont souvent très utiles.
Fournir tests et documentation quand c’est possible - Si vous suggérez des changements, envisagez d’ajouter des tests ou de la documentation pour les soutenir. Les tests aident à vérifier le comportement, et la documentation rend le code plus compréhensible. Les futurs contributeurs vous en seront reconnaissants.
Utiliser les Draft PR pour les retours précoces - Si vous hésitez sur des changements, utilisez une Draft PR pour obtenir des retours tôt. Cela aide à repérer les problèmes plus rapidement.

Directives pour les auteurs de PR

Tester vos changements localement - Avant de demander une revue, testez vos changements localement pour vérifier qu’ils fonctionnent. Les reviewers apprécieront cette diligence.
Documenter les choses - Votre PR modifie-t-elle le schéma de configuration d’un module? Introduit-elle une nouvelle API? Change-t-elle le comportement d’un composant d’une façon qui n’est pas évidente? Documentez ces changements dans la description de PR. Tester des changements dans des composants partagés ou frameworks sous-jacents n’est pas toujours possible, surtout quand les tests ne couvrent pas le cas exact. Dans ces situations, documentez ce que vous avez changé et pourquoi.
Suivre les conventions de code - Nous avons défini des conventions de code pour O3. Assurez-vous que votre code les respecte. Si ce n’est pas le cas, corrigez-le avant de demander une revue.
Être ouvert aux retours - Les revues de code sont une occasion d’apprendre. Soyez ouvert aux retours et prêt à ajuster votre code. Le but est de vous aider à l’améliorer, pas de vous critiquer.
Donner suite aux revues et suggestions - Après avoir reçu des retours, répondez-y et appliquez les suggestions. Si quelque chose n’est pas clair, demandez des précisions. Si vous ne savez pas comment faire un changement, demandez de l’aide. Plus vous échangez autour des retours, meilleur sera le code. Ajoutez les suggestions dans un batch pour pouvoir les pousser en un seul commit.
Garder votre branche de PR à jour - Si votre PR reste ouverte longtemps, mettez-la à jour avec la branche principale pour qu’elle soit relue par rapport au code courant. Les dépôts OpenMRS utilisent le squash merge, donc suivez le flux habituel du dépôt sans vous soucier de rendre parfait l’historique intermédiaire de la branche.
Faire une auto-revue - Avant d’ouvrir une PR, relisez vous-même votre code. Cherchez les fautes, erreurs de logique, problèmes de formatage et autres détails. Plus vous en trouvez vous-même, moins les reviewers auront à signaler.
Lire des pull requests existantes - Ce n’est pas strictement nécessaire, mais lire des PR existantes peut aider à comprendre les attentes des reviewers et à mieux préparer votre propre revue.
Être patient - Les revues prennent du temps. Donnez aux reviewers le temps de répondre. Si vous n’avez pas de nouvelles depuis un moment, vous pouvez demander poliment une mise à jour.
Chercher des critiques constructives - Ayez des standards élevés pour votre travail. Cherchez les occasions de demander à quelqu’un de l’améliorer. Demandez des revues de code, de design et des évaluations par les pairs. La critique du travail n’est pas une critique de la personne.

Directives pour les reviewers

Poser des questions - Si vous ne comprenez pas quelque chose dans le code, posez une question. Quand la raison d’un changement n’est pas claire, demandez une explication. Cela aide à comprendre le code et à fournir un retour utile.
Donner un retour - Soyez précis sur ce qui fonctionne ou non. Si vous avez une suggestion, dites clairement quoi changer et pourquoi. Plus le retour est précis, plus il est facile à traiter.
Évaluer si le code atteint son objectif - Vérifiez que le code soumis accomplit bien ce qu’il est censé accomplir. Chaque changement doit avoir un objectif précis, et le code doit être évalué selon cet objectif.
Évaluer la maintenabilité - Vérifiez si le code est maintenable. Est-il facile à lire et comprendre? Bien organisé? Facile à modifier ou étendre? Bien documenté? Testable? Tous ces points comptent lors d’une revue.
Évaluer le respect des conventions du projet - Nous avons défini des conventions de code pour O3. Lors d’une revue, vérifiez que le code les respecte. Si ce n’est pas le cas, donnez un retour à l’auteur.
Réfléchir à votre propre approche - Votre approche serait-elle radicalement différente? Si oui, demandez-vous si elle est meilleure. Si c’est le cas, proposez-la à l’auteur. Sinon, considérez que l’approche de l’auteur peut être meilleure et donnez un retour en conséquence.
Considérer les effets de bord indésirables - Le changement casse-t-il un comportement existant? Introduit-il des bugs? Dégrade-t-il les performances? Introduit-il une vulnérabilité de sécurité? Ces questions sont importantes.
Lire les tests - Si la PR inclut des tests, lisez-les. Testent-ils les bons comportements? Sont-ils bien écrits? Couvrent-ils les cas limites? Si les tests manquent, proposez des améliorations.
Demander des mises à jour de documentation - Si le code nécessite une mise à jour de documentation, demandez-la. La documentation fait partie du développement et doit rester à jour.
Fournir un retour concis et impersonnel - Concentrez-vous sur le code, pas sur l’auteur. Évitez les formulations qui sonnent personnelles et préférez des formulations centrées sur le changement. Cela rend le retour plus constructif.
Laisser du temps à l’auteur - Après avoir donné un retour, laissez à l’auteur le temps de faire les changements. Ne le pressez pas.
Donner une indication claire sur la suite - Si vous voulez relire la PR après les changements, dites-le. Si les changements vous conviennent et que le code est prêt à être fusionné, dites-le aussi.
Être respectueux - Les revues peuvent être sensibles. Le but est d’aider l’auteur à améliorer son code, pas de le critiquer.
Être spécifique - Plus votre retour est précis, plus il est facile pour l’auteur de comprendre et d’appliquer les changements. Les liens vers la documentation ou des exemples sont souvent utiles.
Encouragez autant de contributeurs que possible à s’engager dans une contribution approfondie et significative.
Soyez attentif aux niveaux d’expérience variés des contributeurs OpenMRS.
Évitez le gatekeeping, notamment en insistant trop sur la façon dont les contributeurs ne suivent pas parfaitement le processus.
Encouragez l’ownership du code, notamment en relisant les changements apportés au code et aux projets auxquels vous avez contribué.