# Contribuer à PEFT

Nous sommes ravis d'accepter des contributions à PEFT. Si vous prévoyez de contribuer, veuillez lire ceci afin de rendre le processus aussi fluide que possible.

## Discuter et obtenir l'approbation avant d'ouvrir une PR

Avant d’ouvrir une pull request (y compris un brouillon), ouvrez ou trouvez un issue dans [huggingface/peft](https://github.com/huggingface/peft/issues) et discutez de votre contribution proposée. S’il existe déjà un issue et que quelqu’un y travaille déjà, a déclaré son intention d’y travailler, ou a une PR ouverte, vous ne devez pas soumettre une PR distincte. Attendez qu’un mainteneur de PEFT ou un membre de Hugging Face approuve explicitement la proposition. Si vous ouvrez un issue, gardez la longueur et la complexité de la description proportionnelles à la complexité de l’issue. Souvent, une description courte avec un reproducteur est plus précieuse qu’une description longue.

Un commentaire d’approbation contient le message `/peft-triage approved`. Il peut également indiquer le nom du contributeur assigné, par exemple `/peft-triage approved username` ou `/peft-triage approved @username`. Ouvrir une PR pour un problème auquel vous n’êtes pas assigné entraînera la fermeture de ladite PR.

Liez le problème ouvert et approuvé dans la description de votre PR en utilisant `#123`, `huggingface/peft#123` ou `https://github.com/huggingface/peft/issues/123`. À titre d’exception, les mainteneurs peuvent désigner des discussions de longue durée spécifiques qui peuvent être référencées par leur URL GitHub complète, sans commentaire d’approbation distinct. Si vous référencez plusieurs problèmes ou discussions, une seule référence valide suffit.

Un flux de travail automatisé vérifie que les PR sont associées à des problèmes ouverts ou à des discussions approuvés. Les PR sans référence valide sont automatiquement fermées avec une explication. Vous pouvez obtenir l’approbation du problème, mettre à jour la description de la PR et rouvrir la même PR ; veuillez ne pas en créer de nouvelle. Si vous estimez que votre PR a été fermée à tort, contactez les mainteneurs sur la PR.

Le bot obsolète indépendant peut toujours fermer les éléments inactifs, même s’ils sont étiquetés `triaged`. Si vous estimez que les mainteneurs ont négligé votre contribution, vous pouvez les solliciter, mais pas avant deux semaines d’inactivité.

## Installation

Suivez ces étapes pour commencer à contribuer :

1. Fork the [repository](https://github.com/huggingface/peft) en cliquant sur le bouton « Fork » de la page du dépôt. Cela crée une copie du code sous votre compte utilisateur GitHub.

2. Clonez votre fork sur votre disque local et ajoutez le dépôt de base en tant que distant. La commande suivante suppose que votre clé SSH publique est téléversée sur GitHub. Consultez le guide suivant pour plus d'[informations](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).

   ```bash
   git clone git@github.com:<your Github handle>/peft.git
   cd peft
   git remote add upstream https://github.com/huggingface/peft.git
   ```

3. Créez une nouvelle branche pour y stocker vos modifications de développement, et faites-le pour chaque nouvelle PR sur laquelle vous travaillez.

   Commencez par synchroniser votre branche `main` avec la branche `upstream/main` (plus de détails dans la [documentation GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)) :

   ```bash
   git checkout main
   git fetch upstream
   git merge upstream/main
   ```

   Une fois que votre branche `main` est synchronisée, créez une nouvelle branche à partir de celle-ci :

   ```bash
   git checkout -b a-descriptive-name-for-my-changes
   ```

   Ne **travaillez pas** sur la branche `main`.

4. Configurez un environnement de développement en exécutant la commande suivante dans un environnement conda ou un environnement virtuel que vous avez créé pour travailler sur cette bibliothèque :

   ```bash
   pip install -e ".[test]"
   ```

   (Si PEFT était déjà installé dans l’environnement virtuel, désinstallez-le avec `pip uninstall peft` avant de le réinstaller.)

Si vous débutez dans la création d'une pull request, suivez le guide [Creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) de GitHub.

## Tests et contrôles de qualité du code

Quelle que soit la nature de la contribution (sauf s’il ne s’agit que de la documentation), vous devez exécuter les tests et les contrôles de qualité du code avant de créer une PR afin de vous assurer que votre contribution ne casse rien et respecte les standards du projet.

### Exécution des tests et des vérifications

Nous fournissons un Makefile pour exécuter les tests nécessaires. Exécutez le code ci-dessous pour le test unitaire :

```sh
make test
```

Exécutez l'une des commandes suivantes pour vérifier uniquement la qualité et le style du code, ou pour les vérifier et les corriger :

```sh
make quality  # just check
make style  # check and fix
```

L’exécution de `make quality` vérifie également si toutes les méthodes/classes de l’API publique de PEFT (c’est-à-dire tout ce qui est mentionné dans `peft.__all__`) sont documentées. Ces erreurs ne peuvent pas être corrigées par `make style` ; vous devez vous assurer de documenter les nouveaux éléments de l’API publique dans la documentation pour corriger cette erreur.

Vous pouvez également configurer [`pre-commit`](https://pre-commit.com/) pour exécuter automatiquement ces correctifs en tant qu'accroches de commit Git.

```bash
$ pip install pre-commit
$ pre-commit install
```

L’exécution de tous les tests peut prendre un certain temps, il est donc plus efficace, pendant le développement, de n’exécuter que les [tests spécifiques à votre modification](https://docs.pytest.org/en/6.2.x/usage.html#specifying-tests-selecting-tests), par exemple via :

```sh
pytest tests/<test-file-name> -k <name-of-test>
```

Cela devrait se terminer beaucoup plus rapidement et permettre une itération plus rapide.

### Ajout de tests

Pour un guide général sur l'ajout de nouveaux tests, consultez `tests/README.md`.

Si votre modification est spécifique à une configuration matérielle (par exemple, elle nécessite CUDA), consultez [`tests/test_gpu_examples.py`](https://github.com/huggingface/peft/blob/1c1c7fdaa6e6abaa53939b865dee1eded82ad032/tests/test_gpu_examples.py) et [`tests/test_common_gpu.py`](https://github.com/huggingface/peft/blob/1c1c7fdaa6e6abaa53939b865dee1eded82ad032/tests/test_common_gpu.py) pour vérifier s'il est pertinent d'ajouter des tests à cet endroit. Si votre modification peut avoir un impact sur l'enregistrement et le chargement des modèles, veuillez exécuter les tests avec le drapeau `--regression` pour déclencher les tests de régression.

## PRs obsolètes

Il peut arriver que, pendant que vous travaillez sur votre PR, la base de code sous-jacente change en raison d’autres modifications fusionnées. Si cela se produit – en particulier en cas de conflit de fusion – veuillez mettre à jour votre branche avec les dernières modifications. Il peut s’agir d’une fusion ou d’un rebase, et nous effectuerons un squash and merge de la PR une fois qu’elle sera prête. **Évitez les force pushes** pour faciliter les revues.

## Description de la PR

Lors de l’ouverture d’une PR, veuillez fournir une description claire de la modification que vous proposez et référencer le problème approuvé tel que décrit ci-dessus. S’il est lié à d’autres problèmes ou PR, veuillez les référencer également. Fournir une bonne description aide non seulement les relecteurs à examiner votre code de manière plus efficace et plus rapide, mais elle peut aussi être utilisée plus tard (comme base) pour le message de commit, ce qui facilite la maintenance à long terme du projet.

Gardez la longueur et la complexité de la description de la PR en adéquation avec la modification. Nous n'avons pas besoin de dix paragraphes d'explication pour une modification triviale d'une seule ligne. Ne reformulez pas ce qui est évident en consultant le diff (par exemple « Fixed the typo in 'foobaar' »).

Si votre code apporte des modifications non triviales, il est également judicieux d’ajouter des commentaires pour les expliquer. Par exemple, si vous avez dû itérer sur votre implémentation à plusieurs reprises parce que la méthode la plus évidente ne fonctionnait pas, c’est un bon indicateur qu’un commentaire de code est nécessaire.

Le cas échéant, indiquez comment vous avez testé la modification, par exemple en montrant la commande de test `pytest` ou le code de reproduction.

## Retour du relecteur

Après avoir soumis votre PR, un mainteneur donnera généralement un retour dans les deux jours. Si vous ne recevez aucun retour dans les deux semaines, votre PR a peut-être échappé à leur attention ; n’hésitez pas à relancer les mainteneurs à ce moment-là, mais pas avant.

Si le relecteur fournit des commentaires en ligne, ne les marquez pas comme résolus si vous y avez répondu. Laissez ces commentaires ouverts, car ils aident le relecteur à reprendre son travail.

Après avoir traité les retours des évaluateurs, prévenez l'évaluateur pour qu'il sache que la PR est prête à être examinée.

## Corrections de bogues

Veuillez décrire les circonstances qui ont conduit au bug. S'il existe un problème existant, veuillez y faire référence (par exemple, « Resolves #12345 »).

Idéalement, lorsqu'un correctif de bug est fourni, il doit être accompagné d'un test pour ce bug. Le test doit échouer avec le code actuel et réussir avec le correctif. Ajoutez un commentaire au test qui référence le problème ou la PR. Sans test, il est plus difficile de prévenir les régressions à l'avenir.

## Améliorations de la documentation

Nous sommes ravis de recevoir des correctifs pour les liens cassés et la documentation manquante ou peu claire. Prendre soin des exemples, en s’assurant qu’ils sont à jour et fonctionnent correctement dans cet environnement en constante évolution, est également très apprécié.

Veuillez vous abstenir d’envoyer des pull requests qui *ne* corrigent que des erreurs de frappe, car elles génèrent généralement plus de travail qu’elles n’en évitent. De telles modifications sont mieux regroupées avec des correctifs plus substantiels (comme la correction de liens cassés ou l’extension/mise à jour de la documentation).

## Ajouter une nouvelle méthode de fine-tuning PEFT

De nouvelles méthodes de fine-tuning à efficacité paramétrique sont développées en permanence. Si vous souhaitez ajouter une nouvelle méthode prometteuse à PEFT, veuillez suivre les étapes ci-dessous.

1. Si vous n'êtes _pas_ l'auteur de l'article original, vérifiez s'il existe des implémentations existantes et confirmez auprès des auteurs qu'ils ne prévoient pas de soumettre eux-mêmes une demande de pull.
2. Ouvrez une proposition de problème et attendez une approbation explicite, comme décrit ci-dessus, avant de commencer les travaux d'intégration principale listés ci-dessous.
3. Consultez les derniers commits pour découvrir les nouvelles méthodes PEFT ajoutées, afin de vous en inspirer.
4. Une fois la proposition approuvée, il peut être utile d’ouvrir une PR en brouillon tôt, dès que la méthode fonctionne de manière basique et que les premiers tests passent, puis de demander des retours. Référencez le problème approuvé dans la description de la PR en brouillon.

### Intégration au cœur d'une nouvelle méthode PEFT

- [ ] Ouvrir un ticket sur `huggingface/peft` et obtenir une approbation explicite avant d'investir trop de travail.
- [ ] Lier la source de la méthode, généralement l’article final ou une autre référence primaire stable. Nous souhaitons éviter les travaux encore en cours de révision, car l’implémentation doit être stable.
- [ ] Ajouter une nouvelle entrée `PeftType` dans `src/peft/utils/peft_types.py`.
- [ ] Créez un nouveau package de tuner sous `src/peft/tuners/` avec les fichiers dont votre méthode a besoin (généralement : `config.py`, `model.py`, `layer.py` et `__init__.py`).
- [ ] Enregistrez la méthode dans le tuner `__init__.py` avec `register_peft_method(...)`.
- [ ] Exportez la nouvelle configuration/modèle depuis `src/peft/tuners/__init__.py` et `src/peft/__init__.py`.
- [ ] Si la méthode a besoin de modules cibles par défaut pour les modèles Transformers, ajoutez le mapping dans `src/peft/utils/constants.py`.
- [ ] Ajoutez la méthode à la matrice de tests dans `tests/test_custom_models.py`, car ce sont les tests les plus larges et les plus rapides. Vérifiez que les tests passent avec `pytest tests/test_custom_models.py -k <method-name> -v` et corrigez les échecs le cas échéant.
- [ ] Exécutez les contrôles de style/qualité avec `make style` avant de pousser.
- [ ] Dans la description de la PR, expliquez la méthode, liez le papier, résumez les compromis et listez ce qui a été ajouté.

### PR complète pour ajouter une nouvelle méthode PEFT

- [ ] Assurez-vous que les arguments de configuration spécifiques à la méthode sont bien nommés et expliqués, sans supposer que l'utilisateur connaît parfaitement l'article.
- [ ] Respectez les conventions de nommage et de codage de PEFT.
- [ ] Assurez-vous de ne pas avoir accidentellement enregistré des modifications non liées, par exemple des fichiers non liés modifiés par le formateur de code.
- [ ] Si certains choix d’implémentation ne sont pas évidents, documentez-les à l’aide d’un commentaire de code.
- [ ] Compléter la suite de tests complète (`test_config.py`, `test_decoder_models.py`, etc.) en ajoutant la méthode PEFT à la matrice de tests. Assurez-vous que les tests passent.
- [ ] Ajouter la documentation dans `docs/source/package_reference/` avec une brève explication, un lien vers l’article, un extrait d’utilisation et des blocs autodoc. Expliquer les avantages et les inconvénients par rapport à d’autres méthodes comme LoRA. Enregistrer cette page de documentation dans `docs/source/_toctree.yml`.
- [ ] Ajouter un exemple exécutable sous `examples/` (il peut s’agir d’une copie d’un exemple existant), avec un court `README.md`.
- [ ] Consultez les benchmarks dans `method_comparison/` et ajoutez les paramètres d’expérimentation pour votre nouvelle méthode. C’est un bon endroit pour vérifier que la méthode PEFT s’entraîne comme prévu. Incluez une ou deux configurations de benchmark raisonnables (une par défaut, une optimisée pour le benchmark).
- [ ] Recommandé : ajouter une prise en charge générique de la quantification. Plutôt que d’ajouter explicitement des types de couches de quantification pour chaque méthode de quantification, prenez en charge la quantification générique. À titre d’exemple, consultez la façon dont elle est implémentée dans [BOFT](https://github.com/huggingface/peft/tree/main/src/peft/tuners/boft). Étendez https://github.com/huggingface/peft/blob/main/tests/test_quantization.py en y ajoutant votre méthode PEFT. Demandez de l’aide aux mainteneurs si nécessaire.

## Apporter des modifications aux méthodes PEFT existantes

Si vous apportez une modification à une méthode PEFT qui pourrait potentiellement modifier ses sorties, invalidant ainsi les points de contrôle déjà entraînés, des précautions supplémentaires sont nécessaires. Veuillez consulter la description située à https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md pour plus de détails. Les instructions qui s’y trouvent s’adressent aussi bien aux humains qu’aux IA.

## Ajouter d'autres fonctionnalités

Ouvrez d'abord un ticket sur GitHub avec une proposition d'ajout de la nouvelle fonctionnalité et attendez une approbation explicite, comme décrit ci-dessus. De cette manière, vous pouvez discuter avec les mainteneurs de la pertinence d'ajouter la fonctionnalité avant d'y consacrer trop de temps pour son implémentation.

Les nouvelles fonctionnalités doivent généralement être accompagnées de tests et de documentation ou d’exemples. Sans ces derniers, les utilisateurs auront du mal à découvrir votre nouvelle fonctionnalité.

Les modifications apportées au code doivent être implémentées de manière rétrocompatible. Par exemple, le code existant doit continuer à fonctionner de la même manière après la fusion de la fonctionnalité.

