Contribuer à PHP: comment contribuer au manuel de PHP

Cette série en deux parties explore comment contribuer au projet PHP, en se concentrant sur la documentation dans la première partie. Nous couvrirons les demandes de compte et les étapes post-approbation.

Points clés:

• La contribution à la documentation de PHP améliore la langue et stimule votre expertise PHP. Cela peut également conduire à un compte php.net, influençant la direction de la langue.
• La documentation utilise DocBook XML; La familiarité est utile mais pas obligatoire.
• Les débutants peuvent utiliser l'éditeur en ligne pour des correctifs simples. La révision des directives de style à l'avance est recommandée.
• Les contributeurs fréquents ou ceux qui ont besoin de modifications approfondies doivent configurer les documents localement et demander un compte php.net. Cela implique la création d'un répertoire, le clonage des documents et la configuration des mots clés SVN.
• Les contributions incluent les corrections de bogues, les traductions, l'expansion du contenu existant, la documentation des fonctionnalités sans papiers et les améliorations générales.

Pourquoi contribuer?

PHP, étant open-source, prospère sur la participation communautaire. Une participation accrue profite à tout le monde. Qu'il s'agisse d'améliorer la documentation, de corriger les bogues ou d'ajouter des fonctionnalités, chaque contribution compte. La participation active approfondit vos connaissances PHP et vous permet de demander un compte PHP.NET, en façonnant l'avenir de la langue.

Comprendre la documentation de PHP

La documentation est dans DocBook XML. Les connaissances antérieures ne sont pas strictement nécessaires; La syntaxe XML est facilement apprise.

La structure du répertoire est:

doc-base contient des outils pour convertir la documentation XML. en détient la documentation anglaise (d'autres langues utilisent leurs codes à deux lettres). reference contient des répertoires spécifiques à une extension (fonctions pour les extensions procédurales, les dossiers de classe pour ceux orientés objet). Chaque dossier d'extension comprend book.xml (page de destination) et versions.xml (Informations de versioning).

La documentation est actuellement basée sur SVN (bien que migrant vers GIT). La configuration locale nécessite une familiarité SVN.

Contributeurs pour la première fois

Commencez par utiliser l'éditeur de documentation en ligne. Cela permet la connexion et la soumission à OAuth de patchs simples. L'utilisation cohérente du compte simplifie les contributions de suivi pour les futures applications de compte php.net.

Familiarisez-vous avec les directives de style avant de soumettre des correctifs.

Exemple: Résolution du bug # 71716

Ce bogue rapporte une classe client MongoDB mal conforme à des noms de noms dans un échantillon. Après vérification, utilisez l'éditeur en ligne pour corriger l'espace de noms.

Embed vidéo: https://www.php.cn/link/14aa36297925d3c82891d74fa28d7df1 (Remplacez par du code emballé réel si nécessaire)

Configuration locale

L'éditeur en ligne est limité; Pour des contributions plus substantielles, configurez les documents localement et demandez un compte php.net.

1. Créer un répertoire phpdocs.
2. Clone les documents à l'aide de SVN: svn checkout https://svn.php.net/repository/phpdoc/modules/doc-en
3. Clone PhD (outil de rendu): git clone http://git.php.net/repository/phd.git
4. Clone Le site Web PHP.NET: git clone http://git.php.net/repository/web/php.git web-php; Supprimez web-php/manual/en et créez un lien symbolique aux documents rendus.
5. Configurez les mots clés SVN dans ~/.subversion/config: *.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL
6. (facultatif) Créez un fichier ref avec des commandes de validation, de construction et de visualisation des documents localement.

Docs Workflow (local)

Après la configuration, mettez à jour les référentiels (svn up et git pull). Modifiez le fichier XML pertinent, validez à l'aide de php ~/phpdocs/doc-en/doc-base/configure.php, créez avec PhD et démarrez le serveur local. Engagez des modifications à l'aide de SVN (svn ci -m "Resolve doc bug #..."), faisant référence au numéro de bogue. Fermez le rapport de bogue de l'onglet "développeur" après les modifications Propagate.

demandant un compte php.net

Après la configuration locale, demandez un compte php.net avec Docs Karma. Bien qu'aucune condition préalable stricte n'existe, la démonstration de contribution active est essentielle. Soumettez le formulaire de demande de compte et envoyez un courriel à phpdoc@lists.php.net expliquant vos intentions, nom d'utilisateur Wiki et contributions passées.

Tâches de documentation

au-delà des corrections de bogues:

• Traductions
• élargir le matériel partiellement documenté
• documenter les fonctionnalités sans papiers
• Améliorations générales

Conseils généraux

• Suivre les directives de style.
• Vérifiez les aspects liés lors de la correction des bogues.
• Écrivez de manière concise.
• Exemple de code séparé de la sortie.
• Assurer la commande correcte de la page.
• supprimer les références php 4.
• version correctement de nouveaux fichiers.
• Consultez la liste de diffusion DOCS FAQ ou PHP-DOCS pour obtenir de l'aide.

Conclusion

Cette partie a couvert deux workflows: l'éditeur en ligne et la configuration locale. La deuxième partie couvrira la contribution au cœur de PHP.

faqs (déplacé à la fin pour un meilleur flux)

• Processus de contribution: Créer un compte, modifier / créer du contenu, traduire, suivre les directives.
• Importance de la contribution: Améliore la qualité de la documentation, le maintient à jour, favorise la communauté.
• Assurer l'acceptation: Suivez les directives, assurez-vous de l'exactitude et de la clarté, obtenez des commentaires.
• Les anglophones non natifs: Les contributions sont les bienvenues; La traduction est une contribution précieuse.
• Erreurs courantes: Ne pas suivre les directives, des informations inexactes / peu claires, le manque de relecture, les changements inutiles.
• Obtenir de l'aide: Utiliser des forums en ligne, des groupes de discussion, des directives de documentation.
• Contribution anonyme: possible, mais un compte est encouragé.
• Fréquence de contribution: varie en fonction de la disponibilité et de l'intérêt.
• Compensation: Généralement le travail de bénévolat.
• Erreurs de rapport: Corrigez-les si un contributeur, sinon signalez à la communauté.

N'oubliez pas de remplacer les URL de l'image d'espace réservé par les URL d'image réelles. J'ai conservé le formatage de l'image et gardé les images dans leurs positions d'origine comme demandé.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!