Aller au contenu principal

Contribution

Docusaurus 2 est actuellement sous développement. Nous avons des adoptants précoces qui ont déjà commencé à l'utiliser. Nous accueillons maintenant les contributeurs pour collaborer sur le prochain Docusaurus.

Le site web Open Source Guides contient une collection de ressources pour les individus, communautés et entreprises qui veulent apprendre à gérer et à contribuer à un projet open source. Les guides suivants seront particulièrement utiles aux contributeurs et aux personnes qui découvrent l'open source :

Code de conduite#

Facebook a adopté un Code de Conduite auquel nous espérons que les participants au projet adhèreront. S’il vous plaît lisez le texte complet afin que vous puissiez comprendre quelles actions seront et ne seront pas tolérées.

Impliquez-vous#

Il y a de nombreuses façons de contribuer à Docusaurus, et beaucoup d'entre elles n'impliquent pas d'écrire de code. Voici quelques idées pour commencer :

  • Commencez à utiliser Docusaurus 2 ! Parcourez les guides de démarrage. Est-ce que tout fonctionne comme prévu ? Dans le cas contraire, nous sommes toujours à la recherche d'améliorations. Faites-le nous savoir en ouvrant une issue.
  • Regardez les issues v2.0. Si vous trouvez une issue que vous souhaitez corriger, ouvrez une pull request. Les issues marquées comme Good first issue sont un bon point de départ.
  • Aidez-nous à améliorer la documentation. Déposez une issue si vous trouvez quelque chose de confus ou qui peut être amélioré. Nous avons également une umbrella issue for v2 docs où nous planifions et travaillons sur toutes les docs v2. Vous pouvez y choisir un morceau pour y travailler.
  • Jetez un œil aux fonctionnalités demandées par d'autres membres de la communauté et envisagez d'ouvrir une pull request si vous voyez quelque chose sur lequel vous voulez travailler.

Les contributions sont les bienvenues. Si vous pensez avoir besoin d'aide pour planifier votre contribution, s'il vous plaît envoyez-nous un message sur Twitter à @docusaurus et faites-nous savoir que vous cherchez de l'aide.

Rejoignez notre canal Discord#

Pour participer au développement de Docusaurus 2, rejoignez le canal #docusaurus-2-dev.

Notre processus de développement#

Docusaurus utilise GitHub comme source de vérité. L’équipe principale y travaillera directement. Tous les changements seront publics dès le début.

Lorsqu'un changement fait sur GitHub est approuvé, il sera vérifié par notre système d'intégration continue, CircleCI.

Signaler de nouvelles issues#

Lors de l'ouverture d'une nouvelle issue, assurez-vous toujours de remplir le template de l'issue. Cette étape est très importante ! Si vous ne le faites pas, votre issue ne sera pas gérée en temps opportun. Ne le prenez pas personnellement si cela se produit, et n'hésitez pas à ouvrir un nouvelle issue une fois que vous avez recueilli toutes les informations requises pour le template.

  • Une issue, un bogue : Veuillez signaler un seul bogue par issue.
  • Fournissez des étapes de reproduction : Listez toutes les étapes nécessaires pour reproduire le problème. La personne qui lit votre rapport de bogue devrait être en mesure de suivre ces étapes pour reproduire votre problème avec un effort minime.

Signaler des bugs#

Nous utilisons GitHub Issues pour nos bogues publics. Si vous souhaitez signaler un problème, jetez un coup d'œil et voyez si quelqu'un a déjà ouvert une issue à ce sujet. Si vous êtes certain qu'il s'agit d'un nouveau bogue non signalé, vous pouvez soumettre un rapport de bogue.

Si vous avez des questions sur l'utilisation de Docusaurus, contactez le compte Twitter Docusaurus @docusaurus, et nous ferons de notre mieux pour répondre à vos questions.

Vous pouvez également enregistrer les issues sous la forme de demandes de fonctionnalités ou d'améliorations. Si vous voyez quelque chose que vous souhaitez implémenter, créez une issue avec le template feature

Signaler des bugs de sécurité#

Facebook a un programme de bounty pour une divulgation sûre des bogues de sécurité. En gardant cela à l'esprit, veuillez ne pas déposer d'issues publiques; passez en revue le processus décrit sur cette page.

Test de nouvelles fonctionnalités#

Vous pouvez devenir un adoptant précoce des nouvelles fonctionnalités en utilisant la balise @canary npm dist et tester les nouvelles fonctionnalités sur votre site dès que la pull-request est fusionnée. Cela nous aide à détecter les problèmes avant la publication officielle.

Travailler sur le code Docusaurus#

Installation#

  1. Assurez-vous que vous avez Yarn installé
  2. Après avoir cloné le dépôt, exécutez yarn install à la racine du dépôt
  3. Pour démarrer un serveur de développement local servant la documentation de Docusaurus, allez dans le répertoire website et exécutez yarn start

Sémantique des messages de commit#

Découvrez comment une modification mineure de votre style de message de commit peut faire de vous un meilleur programmeur.

Format : <type>(<portée>): <sujet>

<portée> est facultatif

Exemple

feat: allow overriding of webpack config^--^  ^------------^|     ||     +-> Résumé du contenu.|+-------> Type: chore, docs, feat, fix, refactor, style, ou test.

Les différents types de commits :

  • feat: (nouvelle fonctionnalité pour l'utilisateur, ce n'est pas une nouvelle fonctionnalité pour le script de build)
  • fix: (correction de bug pour l'utilisateur, ce n'est pas une correction pour un script de build)
  • docs: (modifications de la documentation)
  • style: (formatage, points virgule manquants, etc - aucun changement de code de production)
  • refactor: (refactorisation du code de production, par exemple. renommer une variable)
  • test: (ajout de tests manquants, refactorisation des tests; aucun changement de code de production)
  • chore: (mise à jour des tâches de grunt, etc - pas de changement de code de production)

Utilisez des minuscules et non des majuscules !

Conventions de code#

Guide de Style#

Prettier attrapera la plupart des problèmes de style qui peuvent exister dans votre code. Vous pouvez vérifier l'état de votre style de code en exécutant simplement npm run plus prettier.

Cependant, il y a encore des styles que Prettier ne peut pas traiter.

Général#

  • Le plus important: regardez autour de vous. Appliquez le style utilisé dans le reste du projet. Cela inclut la mise en forme, le nommage des fichiers, le nommage des choses dans le code, le nommage dans la documentation.
  • « Attractif»

Documentation#

  • Ne coupez pas les lignes à 80 caractères - configurez votre éditeur pour qu'il ne coupe pas les lignes lors de l'édition de la documentation.

Pull requests#

Votre première pull request#

Vous avez donc décidé de contribuer au code en amont en ouvrant une pull request. Vous avez investi une bonne partie de votre temps, et nous l'apprécions. Nous ferons de notre mieux pour travailler avec vous et examiner la PR.

Vous travaillez sur votre première Pull Request ? Vous pouvez apprendre comment grâce à cette série de vidéos gratuites :

Comment contribuer à un projet Open Source sur GitHub

Nous avons dressé une liste de issues adaptés aux débutants pour vous aider à vous familiariser avec le code de Docusaurus et avec notre processus de contribution. C'est un endroit idéal pour commencer.

Proposer un changement#

Si vous souhaitez demander une nouvelle fonctionnalité ou une amélioration mais que vous ne pensez pas encore ouvrir une pull request, vous pouvez également déposer une issue avec le template feature.

Si vous avez l'intention de changer l'API publique (par exemple, quelque chose dans docusaurus.config.js), ou apporter des modifications non triviales à l'implémentation, nous vous recommandons de déposer un problème avec le template proposal et d'inclure [Proposal] dans le titre. Cela nous permet de parvenir à un accord sur votre proposition avant que vous n'y consacriez des efforts importants. Ces types d'issues devraient être rares.

Si vous ne corrigez qu'un bogue, Il est bon de soumettre une pull request tout de suite, mais nous vous recommandons de déposer une issue détaillant ce que vous corrigez. Ceci est utile dans le cas où nous n'acceptons pas cette correction spécifique, mais que nous voulons garder une trace de l'issue.

Envoi d'une pull request#

Les petites pull requests sont beaucoup plus faciles à examiner et plus susceptibles d'être fusionnées. Assurez-vous que la PR ne fait qu'une chose, sinon veuillez la diviser. Il est recommandé de suivre ce style de message de commit.

Veuillez vous assurer que ce qui suit est fait lors de l'envoi d'une pull request :

  1. Forkez le dépôt et créez votre branche à partir du master.
  2. Ajoutez l'entête du droit d'auteur en haut de n'importe quel nouveau code que vous avez ajouté.
  3. Décrivez votre plan de test dans la description de votre pull request . Assurez-vous de tester vos modifications !
  4. Assurez-vous que votre code a été vérifié (yarn prettier && yarn lint).
  5. Assurez-vous que vos tests Jest passent (yarn test).
  6. Si vous ne l'avez pas déjà fait, signez le CLA.

Toutes les pull requests doivent être ouvertes sur la branche master.

Plan de test#

Un bon plan de test contient les commandes exactes que vous avez exécutées et leur résultat, fournit des captures d'écran ou des vidéos si la pull request modifie l'interface utilisateur.

  • Si vous avez modifié des API, mettez à jour la documentation.

Modifications importantes#

Lors de l'ajout d'un changement important, suivez ce modèle dans votre pull request :

### New breaking change here
- **Who does this affect**:- **How to migrate**:- **Why make this breaking change**:- **Severity (number of people affected x effort)**:

Entête du droit d'auteur pour le code source#

Copiez et collez ceci en haut de votre (vos) fichier(s) :

/** * Copyright (c) Facebook, Inc. and its affiliates. * * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. */

Contrat de licence du contributeur (CLA)#

Pour pouvoir accepter votre pull request, nous avons besoin que vous nous soumettiez une CLA. Vous n'avez besoin de le faire qu'une seule fois, donc si vous avez fait cela pour un autre projet open source Facebook, vous êtes prêt à démarrer. Si vous soumettez une pull request pour la première fois, le GitHub Bot Facebook répondra avec un lien vers le formulaire de CLA. Vous pouvez aussi compléter votre CLA ici.

Que se passe-t-il ensuite?#

L'équipe principale de Docusaurus surveillera les pull requests. Aidez-nous en gardant la cohérence des pull requests en suivant les directives ci-dessus.

Licence#

En contribuant à Docusaurus, vous acceptez que vos contributions soient sous licence MIT.