Développement

From The Document Foundation Wiki
Jump to: navigation, search

Votre première compilation

Réussir votre première compilation de LibreOffice peut être une tâche décourageante et/ou intimidante. Vous trouverez une explication pas à pas qui vous guidera dans cette épreuve sur la page How to Build.

Comment s'impliquer ?

La base de code peut paraître impressionnante au premier abord. Consultez la page Code Overview pour un aperçu de la fonction de chaque répertoire et dépôt.

Vous pouvez suivre le développement grâce à une liste de tous les commits en quasi-temps réel (service grâcieusement fourni par cia.vc).

Rapporter des bugs

Rapporter des bugs et vérifier qu'ils sont toujours valides constitue une contribution importante au projet. Vous trouverez des information sur la façon de rapporter des bugs ici.

Trouver un problème à résoudre

Une liste de Modifications Faciles a été dressée afin de vous aider à trouver votre première tâche. Bien sûr, il y a également un gestionnaire de bug recensant les problèmes non résolus, certains étant catégorisés comme EasyHacks pour les retrouver plus facilement. Et il y a une liste d'idées folles qui a été commencée.

Une page pour rassembler les idées afin d'améliorer l'expérience utilisateur sur l'interface par défaut est disponible sur Default UI Improvements.

Fonctionnalités demandées par les entreprises

Une autre liste de demandes intéressante est constituée par les besoins exprimées par de grandes entreprises, dans lesquelles les DSI on des contraintes en terme de déploiement et d'assistance. Nous avons collecté sur cette page des demandes concernant LibreOffice déjà exprimées par des entreprises. Si vous voulez rendre votre patron heureux, aidez-nous à les implanter !

Préparer des correctifs

Tout d'abord, il est préférable de suivre le Style de Code propre à OpenOffice.org et, de façon générale, les conventions de code (comme les règles de nommage, etc.). Afin de préparer un correctif, vous pouvez l'envoyer à la mailing list des développeurs. Supposons que vous ayez démarré sur une branche master non modifiée. Voici la procédure à suivre :

  • Modifiez le code comme vous le souhaitez (si vous prévoyez des modifications en profondeur, envisagez d'utiliser des feature branches)
  • Propagez vos modifications en local sous git. La première option ajoute tous les fichiers modifiés tandis que la seconde vous permet de sélectionner les fichiers faisant partie du commit :
git commit -a

 ... ou ...

git add <file1> <file2> ...
git commit

Lorsque vous saisissez un message de commit, placez un résumé de vos modifications sur la première ligne. La deuxième ligne doit être laissée blanche et vous pouvez expliquer dans les détails chaque modification à partir de la troisième.

  • créez le patch que vous souhaitez envoyer. Si toutes vos modifications sont dans une même arborescence git, vous pouvez utiliser ce dernier directement pour récupérer les modificiations effectuées sur votre branche sous forme de fichier diff :
git format-patch HEAD~1

Si vous avez effectué des modifications sur plusieurs dépôts, vous pouvez récupérer l'intégralité des modifications en une fois avec la commande :

./g format-patch --suffix=.@REPO@.patch -o/home/moi/unrepertoire/où_mettre_mes_patches origin/master..HEAD
  • après l'envoi de votre patch, si vous voulez revenir à la branche master originelle, vous pouvez suivre ces instructions pour revenir à une branche propre.

Alternative : Proposer des branches git

LibreOffice étant développé en utilisant git signifie qu'il est possible d'en utiliser toutes les fonctionnalités. Par exemple, vous pouvez préparer une branche à partir de laquelle les committers pourront récupérer vos patches. Si vous envisagez cette solution, il peut être utile de vous coordonner avec un commiter avant de la mettre en place pour savoir si cette façon de procéder lui convient.

Utiliser Git pour le développement de LibreOffice

Git est un Système de Contrôle de Version Distribué (Distributed Version Control System; DVCS). Il s'agit d'un système simple mais très puissant, toutefois, si vous n'êtes pas familier avec les DVCS, cela peut être déroutant. Heureusement, il y de bonnes ressources sur le web pour apprendre à utiliser Git. Si vous ne connaissez pas le système, vous devriez consulter http://git-scm.com/. Le reste de cet article suppose une connaissance basique du fonctionnement de Git.

En raison de la taille importante du projet, le code source de LibreOffice est distribué sur 19 dépôt Git distincts. Cela procure des défis intéressants, même pour les habitués de Git.

./g

Dans la pluspart des cas, vous n'aurez besoin que de travailler dans le dépôt 'core', mais dans certain cas il vous sera necessaire d'effectuer des opérations git sur l'ensemble des dépôts - particulierement lors de manipulations de branches. Pour ces cas il exist un petit utilitaire appelé g, situé dans ./g

La plupart des commandes de la forme git xxxx, peuvent être remplacées par ./bin/g xxxx qui signifie "lancer git xxxx sur chaque dépôt".

Par défaut, pour la plupart des commandes git, si une erreur survient lors de l'exécution de la commande dans l'un des dépôts, ./bin/g s'arrêtera et n'appellera pas la commande pour le reste des dépôts. Pour passer outre ce comportement, vous pouvez utiliser ./bin/g -f xxxx.

Grep

Vous pouvez utiliser "git grep" au lieu de grep qui est bien plus rapide sur les arborescence important puisqu'il ne prend en compte que les fichiers sous contrôle de version. Et vous pouvez utiliser g grep ou ga grep afin d'effectuer une recherche dans tous les dépôts d'un seul coup.

Une autre approche est d'utiliser opengrok un outil web qui peut s'avérer plus rapide que d'effectuer la recherche sur votre propre machine.

Gérer les branches git

Observer les branches en cours

Afin de consulter la branche sur laquelle vous travaillez, utilisez :

~/loroot $ ./g branch

Cette commande dresse la liste des branches locales pour chaque dépôts, celle actuellement active est précédée d'un "*". Chaque dépôt doit indiquer la même branche comme active.

Ajouter -r après la commande branche vous affichera les branches disponibles sur les dépôts distants (c-à-d la liste des branches de fonctionnalités disponibles).

Basculer sur une autre branche

Créons une nouvelle branche 'feature/slicebread' dérivant de origin/master sur tous les dépôts, ce qui nous permettra de développer tranquillement une nouvelle fonctionnalité :

~/loroot $ ./g checkout -b feature/slicebread origin/master

Si vous affichez la branche active, tous les dépôts devraient indiquer 'feature/slicebread'.

Si vous voulez basculer vers une branche existante, utilisez :

~/loroot $ ./g -f checkout -b feature/slicebread origin/feature/slicebread

Cela créera une branche locale 'feature/slicebread' liées à la branche distante feature/slicebread. Le -f oblige bin/g à parcourir tous les dépôts de façon inconditionnelle, même si la branche n'est pas disponible sur l'un d'entre eux.

Revenir en arrière : Si vous voulez retourner sur la branche master et supprimer votre branche locale, assurez-vous de n'avoir aucune modification non propagée, rebasculez sur master puis supprimez votre branche locale feature/slicebread.

~/loroot $ ./g checkout master
~/loroot $ ./g -f branch -D feature/slicebread

Modifier et commiter sur une branche

Maintenant que vous pouvez effectuer vos modifications et compiler à votre guise, ne soyez pas timide pour commiter. Ces commits sont purement locaux et ne seront pas visibles à moins que vous ne les publiiez. Vous pourrez toujours les réorganiser plus tard si vous voulez nettoyer l'historique. Chaque commit devrait contenir un ensemble de modifications cohérent et décrit clairement. La première ligne de la description doit être un résumé concis des modifications (moin de 80 caractères), puis, après une ligne vide, vous pouvez saisir une description plus précise des changements.

Maintenant que vous avez implanté ou avancé sur votre nouvelle fonctionnalité, vous voulez certainement des retours

Tout d'abord, puisque la branche master a certainement changé depuis votre création de branche, vous devriez vous mettre à jour afin que vos modifications soient compatibles avec le HEAD courant.

Pour cela, vous devez vous assurer que vous avez commité tout ce qui est nécessaire et nettoyé votre dépôt afin qu'aucune modification ne soit en attente. Pour rebasculer sur la branche master :

~/loroot $ ./g checkout master

Raffraîchissez votre master :

~/loroot $ ./g pull -r

Revenez sur votre branche :

~/loroot $ ./g checkout feature/slicebread

et utilisez rebase

~/loroot $ ./g rebase origin/master

S'il y a des conflits, vous devrez les résoudre manuellement et reprendre l'opération ensuite.

Il est maintenant temps de publier. Il y a deux cas.

Si vous n'avez pas de dépôts sur lesquels propager ces modifications, vous voudrez certainement préparer un jeu de correctifs afin de les poster sur la Dev-List pour qu'ils soient passés en revue :

~/loroot $ ./g format-patch --suffix=-@REPO@.patch --output-dir=<where_you_want> master..HEAD

Cette commande génèrera un fichier commit avec le nom du dépôt en suffixe, ils seront placés dans le répertoire indiqué. Vous pouvez ensuite les joindre à votre email..

Si vous avez la possibilité de pusher sur un ensemble de dépôts :

~/loroot $ ./g push origin feature/slicebread

Il existe une myriade d'excellents didacticiels, livres et même vidéos sur l'utilisation de git. Vous êtes vivement encouragé à les consulter. L'environnement de développement de LibreOffice se compose de 20 dépots git qui n'en forment qu'un d'un point de vue logique mais qui doivent être gérés individuellement (d'où les scripts g et ga).

Modifier et commiter sur une branche stable

Les branches stables sont créées à partir du master ou d'autres branches stables pour stabiliser le code dans l'optique d'une publication ou de mises à jour. Il existe quelques règles durant la phase de mise au point (beta phase), sont autorisés :

  • les corrections de bugs ;
  • les ajouts de fonctionnalités tardifs lorsqu'ils sont approuvés par le Steering Committee ;
  • les modifications dans les traductions.

Les règles se durcissent à partir du passage en Release Candidate, sont autorisés :

  • les correctifs relus par une seconde personne (voir ci-dessous) ;
  • les modifications dans les traductions ; il est conseillé de demander une vérification sur la liste de diffusion de localisation.

S'il vous plait, ne commitez pas de correctif directement' pendant la phase RC. Veuillez demander à un autre développeur de relire votre code via la liste libreoffice@lists.freedesktop.org ou directement par mail, irc ou sur le rapport de bug associé. Le correctif doit être commité par le relecteur via la commande :

git commit -s --author='Author name <author@mail.address>'


Revenir à un dépôt non modifié

~/loroot $ bin/g reset --hard origin/master

annulera vos modifications (qu'elles soient propagées ou non) et réinitialisera la branche courante à partir de celle du dépôt distant.

Obtenir et utiliser un accès en écriture (commit)

Afin d'obtenir un accès en écriture, vous devez être sponsorisé. Une fois que vous aurez proposé des correctifs pertinents, ce ne sera pas un problème, mais il est plus poli d'attendre que l'on vous le propose. Une fois que cela vous a été proposé (ou que vous avez demandé à quelqu'un de vous sponsoriser), vous devez créer un compte.

Conventions de code

sal_Bool ne doit être utilisé que dans le cadre de UNO, dans les autres cas, lui préférer bool.

Travailler sur des parties spécifiques de libreoffice

Débogage

Notes sur le développement

TODO: add syntaxhighlight