👍🎉 Premièrement, merci de prendre le temps de lire ceci et de contribuer! 🎉👍
Les contributions de tiers nous aide à améliorer et faire grandir QMK. Nous voulons rendre les pull requests et le processus de contribution utile et simple à la fois pour les contributeurs et les mainteneurs. C'est pourquoi nous avons mis en places des directives pour les contributeurs afin que votre pull request puisse être accepté sans changement majeur.
Si vous voulez poser une question sur QMK, vous pouvez le faire sur le sous-reddit OLKB ou sur Discord.
Merci de garder ceci en tête:
QMK est majoritairement écrit en C, avec quelques fonctions et parties spécifiques écrites en C++. Il est destiné aux processeurs intégrés que l'on trouve dans des clavier, particulièrement AVR (LUFA) et ARM (ChibiOS). Si vous maîtrisez déjà la programmation sur Arduino, vous trouverez beaucoup de concepts et de limitations familiers. Une expérience préalable avec les Arduino n'est pas nécessaire à contribuer avec succès à QMK.
Si vous avez besoin d'aide, vous pouvez ouvrir une issue ou un chat sur Discord.
Vous n'avez encore jamais contribué à un projet open source? Vous vous demandez comment les contributions dans QMK fonctionnent? Voici un aperçu rapide!
votre-login-GitHub/qmk_firmware
.git clone https://github.com/login-github/repository-name.git
.git checkout -b nom-de-branche
.git add chemin-de-fichier
pour ajouter les contenus des fichiers modifiés au "snapshot" que git utilise pour gérer l'état du projet, appelé aussi l'index.git commit -m "Insérez une description courte des changements (en anglais)"
pour enregistrer le contenu de l'index avec un message descriptif.git push origin nom-de-branche
.La grande majorité de notre style est plutôt simple à comprendre. Si vous connaissez C ou Python, vous ne devriez pas avoir trop de difficulté avec notre style.
Nous avons un certain nombre de type de changements dans QMK, chacun nécessitant un niveau de rigueur différent. Nous voulons que vous gardiez les directives suivantes en tête quel que soit le changement que vous êtes en train de faire.
git diff --check
avant de commit.make keyboard:your_new_keymap
ne renvoie pas d'erreur.make keyboard:all
ne renvoie pas d'erreur.make all
ne renvoie pas d'erreur.Adjust the fronzlebop for the kerpleplork
The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations.
Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.
La documentation est l'une des manières les plus simples de démarrer la contribution sur QMK. Il est simple de trouver des endroits où la documentation est fausse ou incomplète, et il est tout aussi simple de la corriger! Nous avons aussi grandement besoin de quelqu'un pour éditer notre documentation, donc si vous avez des compétences en édition mais que vous n'êtes pas sûr de savoir où aller, n'hésitez pas demandez de l'aide!
Vous trouverez toute notre documentation dans le répertoire qmk_firmware/docs
, ou si vous préférez utiliser des outils web, vous pouvez cliquer sur le bouton "Suggest An Edit" en haut de chaque page sur https://docs.qmk.fm/.
Lorsque vous donnez des exemples de code dans la documentation, essayez de suivre les conventions de nommage utilisées ailleurs dans la documentation. Par exemple, standardisez les enums en utilisant my_layers
ou my_keycodes
afin de garder une consistance:
enum my_layers {
_FIRST_LAYER,
_SECOND_LAYER
};
enum my_keycodes {
FIRST_LAYER = SAFE_RANGE,
SECOND_LAYER
};
La plupart des contributeurs débutants démarrent avec leurs keymaps personnelles. Nous essayons de garder les standards pour les keymaps pluôt simple (les keymaps reflètent, après tout, la personnalité de leurs créateurs) mais nous demandons que vous suiviez les directives suivantes afin que d'autres puissent découvrir et apprendre de votre keymap.
readme.md
en utilisant la template.Makefile
dans votre dossier de keymap (ils ne sont plus utilisés)%YOUR_NAME%
)Les claviers sont la raison d'être de QMK. Certains claviers sont maintenus par la communauté, alors que d'autre sont maintenus par les gens responsables de la création du clavier. Le fichier readme.md
devrait vous informer de qui maintient le clavier. Si vous avez des questions concernant un clavier en particulier, vous pouvez Ouvrir une issue et tagger le mainteneur dans votre question.
Nous vous demandons aussi que vous suiviez ces directives:
readme.md
en utilisant le template..c
/.h
du nom du dossier parent, par exemple /keyboards/<kb1>/<kb2>/<kb2>.[ch]
Makefile
dans votre dossier de keymap (ils ne sont plus utilisés)%YOUR_NAME%
)Faites attention d'être sûr d'implémenter votre nouvelle fonctionnalité de la meilleure manière qu'il soit avant d'investir beaucoup de travail à son développement. Vous pouvez apprendre les bases de QMK en lisant Comprendre QMK, qui vous donnera une idée du flux du programme QMK. A partir de là, parlez nous afin de définir la meilleure façon d'implémenter votre idée. Il y a deux façons principale de le faire:
Les PR de nouvelles fonctionnalités de de correction de bug affectent tous les claviers. Nous sommes aussi dans un processus de restructuration de QMK. Pour cette raison, il est absolument nécessaire que tout changement important ou significatif soit discuté avant que l'implémentation soit faite. Si vous ouvrez un PR sans nous avoir parlé, préparez-vous à faire des refontes significatives si vos changements ne sont pas compatibles avec ce que nous avons planifié.
Voici quelques choses à garder en tête lorsque vous travaillez sur une fonctionnalité ou un bug fix.
docs/
, soit dans un nouveau fichier, ou dans une partie d'un fichier existant. Si vous ne la documentez pas, personne ne pourra bénéficier de votre dur labeur.Nous vous demandons aussi de suivre ces directives:
Afin de maintenir une vision claire sur comment les choses sont architectuées dans QMK, nous essayons de planifier des refactorisations en profondeur et qu'un collaborateur fasse le changement. Si vous avez une idée de refactorisation, ou une suggestion, [ouvrez une issue] open an issue, nous adorons discuter de comment améliorer QMK.
Note Code De Conduite veut dire que vous avez la responsabilité de traiter tout le monde dans le projet avec respect et courtoisie, peu importe leur identité. Si vous êtes victime d'une attitude ou de commentaires inappropriés, tels que décrit dans notre Code de Conduite, nous sommes là pour vous et nous ferons de notre mieux pour nous assurer que le fautif soit réprimandé, tel que décrit dans notre code.