Contribuer à PHP-Bottle

En tant que logiciel libre, PHP-Bottle dépend de vous pour vivre et parvenir à son but d’aider les développeurs.

PHP-Bottle est encore un tout petit projet, et ne bénéficie pas encore d’un site web. Néanmoins, vous pouvez utiliser cette documentation pour apprendre à l’utiliser et l’améliorer.

Obtenir les sources

Le dépôt de travail et le gestionnaire de tickets sont tous deux hébergés sur Github. Si vous souhaitez contribuer, c’est une bonne idée d’y créer un compte et de forker le dépôt principal. De cette façon, vos modifications seront visibles aux autres développeurs et pourront être discutées publiquement. Même sans compte, vous pouvez cloner le dépôt, ou simplement télécharger l’archive de la dernière version.

Soumettre des patches

La meilleure façon de voir vos changement intégrés dans la branche de développement principale est de forker le dépôt principal sur Github, créer une nouvelle branche liée à une fonctionnalité, et d’envoyer une pull-request. Vous trouverez des exemples de workflows Git qui pourraient vous aider, plus bas dans cette page. Dans tous les cas, veuillez respecter ces règles basiques :

  • Documentation : indiquez ce que fait votre patch. Commentez votre code. Si vous introduisez une nouvelle fonctionnalité, ajoutez-la à la documentation afin que d’autres puissent apprendre son fonctionnement.

  • Tests : écrivez des tests pour prouver que votre code fonctionne comme prévu et ne casse rien. Si vous avez corrigé un bug, écrivez au moins un test traitant le cas de figure qui provoquait le bug. Assurez-vous que tous les tests passent avant de soumettre un patche.

  • Un patch à la fois : ne corrigez qu’un bug, ou n’ajoutez qu’une fonctionnalité, à la fois. Concevez vous patches pour qu’ils puissent être appliqués comme un tout. Maintenez leur code propre, succint et concentré sur l’essentiel. Soyez à jour par rapport à l’upstream : si la branche upstream/master change alors que vous travailliez sur votre patch, faites un rebase ou un pull pour vous assurez que votre patch s’applique toujours sans conflits.

Construire la Documentation

Il vous faut une version récente de Sphinx pour construire la documentation. Nous vous recommandons d’installer Virtualenv via le gestionnaire de paquets de votre distribution, et d’installer Sphinx ensuite pour bénéficier d’une version à jour.

# Install prerequisites
which virtualenv || sudo apt-get install python-virtualenv
virtualenv --no-site-dependencies venv
./venv/pip install -U sphinx sphinx-intl

# Clone or download bottle from github
git clone https://github.com/nergal/php-bottle.git

# Activate build environment
source ./venv/bin/activate

# Build HTML docs
cd php-bottle/docs
make html

Maintenant, pour plus de praticité, vous pouvez vous déplacer dans le dossier _build/html, et lancer un serveur de développement.

python3 -m http.server

Maintenant, ouvrez un navigateur web, et faites-le pointer sur http://localhost:8000 .

Cette documentation est multilingue, donc vous pouvez également travailler sur les traductions. Vous aurez besoin pour cela de Poedit, ou de tout logiciel capable d’éditer des fichiers .po .

Si vous voulez écrire des traductions sur une langue déjà présente, ou bien ajouter une langue, vous aurez tout d’abord besoin de construire les fichiers .po via les commandes suivantes :

make gettext
sphinx-intl update -l fr -p _build/locale

N’oubliez pas de remplacer « fr » par votre propre langue !

Il vous reste à compléter le processus de traduction directement dans Poedit. Les fichiers à traduire sont dans le dossier locale/fr/*.po (n’oubliez pas d’utiliser votre propre code de langue).

Poedit pout générer des fichiers .mo tout seul. Si vous ne pouvez pas, pour quelque raison que ce soit, compiler vos fichiers. mo, il existe une commande pour ça :

sphinx-intl build

Vous pouvez compiler la documentation Sphinx pour votre langue via la commande suivante :

make SPHINXOPTS="-Dlanguage=fr" html

Si vous avez ajouté une nouvelle langue, vous devrez ouvrir un ticket sur Github pour demander l’intégration de cette langue. Entre-temps, vous êtes libre de soumettre vos traductions par des pull-requests.