Joomla! Documentation™

Introduction

Cette documentation a vocation de proposer des informations sur la manière de contribuer au CMS Joomla! via Git et GitHub. Si vous souhaitez faire une simple modification (un seul fichier), il est préférable de consulter cet article : Utiliser l'interface GitHub pour créer des Pull Requests. Si vous souhaitez réaliser des modifications plus complexes ou si vous êtes juste curieux, continuez ici votre lecture !

Git et GitHub c'est quoi ?

Git est un système de contrôle et de distribution de version. C'est un système qui enregistre les modifications dans les fichiers et conserve ces changements dans un fichier historique. Vous pouvez toujours consulter en arrière dans une version antérieure de votre code et restaurer les modifications si vous le souhaitez. En raison de l'historique des archives, Git est très utile lorsque vous travaillez à plusieurs, ensemble sur le même projet.

Voici comment utiliser GitHub. GitHub est un site Web qui permet de gérer les projets Git de manière visuelle. En tant que propriétaire d'un projet, vous pouvez modifier le code et comparer différentes versions. En tant qu'utilisateur du projet, vous pouvez contribuer en faisant une demande d'extraction. Une demande d'extraction est une demande adressée au propriétaire pour extraire du code dans le projet. Vous proposez un morceau de code (peut-être une solution à un bogue) et demandez si le propriétaire du projet souhaite l'utiliser. Si le propriétaire l’aime, il peut le fusionner (ajouter) à son projet.

Joomla! utilise GitHub et Git pour maintenir son code. Tout le monde peut contribuer au logiciel Joomla!. L'URL du projet Joomla! CMS sur GitHub est: https://github.com/joomla/joomla-cms

Bien débuter

Inscrivez-vous à GitHub et installer Git

Tout d'abord, vous devrez vous enregistrer sur GitHub. C'est gratuit et facile à faire. Suivez simplement les étapes fournies.

Une fois que nous sommes inscrits, nous devons installer Git. La dernière version de Git est disponible sur http://git-scm.com. Téléchargez et ouvrez le programme d'installation. Git est un programme CLI (Command Line Interface ou Ligne de Commande). Au début, cela peut être déroutant et un peu effrayant, mais ce document vous guidera tout au long du processus.

Si vous n'êtes pas un utilisateur expérimenté, lancez simplement le programme d'installation et appuyez sur les boutons "Suivant" jusqu'à ce que le programme soit installé. Git n'endommagera pas votre système. Plus tard, vous pourrez le supprimer comme n'importe quel autre programme si vous le souhaitez.

Une fois que nous avons installé Git, nous ouvrons le programme appelé "Git Bash". Une ligne de commande sera ouverte. Nous allons dire à Git notre nom et notre adresse email. Git utilisera ces informations lorsque nous contribuerons à un projet. Avec les commandes suivantes, nous donnons cette information à Git:

git config --global user.name "Your name"
git config --global user.email youremail@mail.com

Dans les commandes ci-dessus et dans toutes les autres commandes données dans cette documentation, chaque ligne est une nouvelle commande. Donc, vous tapez la première ligne, appuyez sur Entrée, puis tapez la deuxième ligne et appuyez sur Entrée.

Nous sommes maintenant prêts à utiliser Git et à aller plus loin dans la configuration de notre installation de test.

Paramétrage d'une installation de test

Pour notre installation de test, nous avons besoin d’un programme de serveur Web afin d’installer et d’exécuter Joomla! sur notre ordinateur. Beaucoup de programmes peuvent le faire, tels que MAMP et XAMPP. Télécharger une distribution de l'un d'eux.

Après l'installation d'un tel programme (j'utilise MAMP dans cette documentation), nous allons installer la dernière version de Joomla!. Dans notre cas, la dernière version de Joomla! n'est pas la dernière version stable. La dernière version de Joomla! est la branche de mise en scène sur GitHub. Tout d’abord, laissez-moi vous en expliquer un peu plus sur GitHub.

Fork et Cloner Joomla!

Sur GitHub, vous pouvez trouver des projets, appelés Repositories ou dépôts. Dans un projet, vous pouvez trouver plusieurs versions. Une telle version s'appelle une branche. Joomla! a les branches suivantes:

• Staging: Cette branche contient les dernières corrections de bugs et les nouvelles fonctionnalités de Joomla!
• Master: Cette branche est la version stable actuelle de Joomla!
• 3.5-dev Cette branche contient les fichiers pour Joomla! 3.5, qui n'est pas stable au moment d'écrire ces lignes.

Sur notre site de test, nous allons utiliser la branche Staging mais si nous devons utiliser cette branche directement, nous avons un problème. Nous ne pouvons pas modifier cette branche car nous n'en sommes pas les propriétaires. Nous allons en faire une copie. Sur GitHub, cela s'appelle Fork ou une fourche. Nous sommes les propriétaires de cette copie afin de pouvoir la modifier. Après modification, nous comparons notre fourche avec le projet original. Ensuite, nous pouvons faire une requête d'extraction pour les modifications que nous avons apportées. Nous en verrons plus à ce sujet plus tard. Vous pouvez créer une branche en cliquant sur le bouton Fork du bouton Répertoire Joomla! Github CMS. Ce bouton est situé en haut à droite de la page.

Après avoir bifurqué, nous allons installer Joomla! sur notre serveur Web local. Accédez au dossier dans lequel vous pouvez exécuter des fichiers sur votre serveur Web. La plupart des programmes utilisent un dossier appelé htdocs. Une fois que nous sommes dans ce dossier, appuyez sur le bouton droit de la souris et cliquez sur: "Git Bash Here". La ligne de commande s'ouvrira pour cet emplacement.

Tapez la commande suivante pour télécharger les fichiers de votre Fork, ou fourche, du logiciel Joomla! CMS sur votre ordinateur. Veuillez remplacer nom d'utilisateur par le nom d'utilisateur que vous utilisez sur GitHub.

git clone https://github.com/username/joomla-cms.git

Pour toutes les commandes données dans cette documentation, vous devez ouvrir Git via les étapes décrites ci-dessus. Gardez cela à l'esprit pour les autres commandes de cette documentation.

Once Git is ready, open your browser and go to the installation on your localhost. Usually the URL is something like: http://localhost/joomla-cms. You will now see the default Joomla! installation process.

Installer Joomla!

The installation of Joomla! for our local test installation is almost the same as a regular installation. There are a two little differences.

For the database settings, the password and username are default. Most often the username is root and the password is also root or there is no password. If you still can't connect to the database, look in the manual for your local Web server for the username and password.

The last difference is the final step of the installation. Normally we must delete the installation folder to go further to the back-end or front-end of Joomla!. For a test installation we can skip this part and go directly to the back-end or front-end. Don't remove the installation folder. It can be very useful when we have to install Joomla again.

Faites vos modifications

Now it is time to made our file changes to Joomla!. All changes we make will be registered and monitored by Git. At any moment you can type the command git status to see which files are modified or untracked. Untracked means that the file at that location is new for Git.

If you made a mistake or you would like to restore a file, use this command:

git checkout path/to/file

If you like to remove all changes you made, use the following commands:

git checkout .
git clean -f -d

The first command resets all files. The second command removes untracked files and folders.

Push the Change to the Fork

After making our changes, we have to upload our changes to our repository on GitHub. After that, we can make a pull request with our changes.

Uploading changes is called push in Git terms. Before we can do that, we have to do something very important. We must create a new branch for our changes. (A branch is a version of our project, remember?) If we don't do that and made our change directly to the staging branch, the first time there won't be a problem. But if we made changes for the second time, and the change we made the first time are not merged yet, all these changes will registered too as new changes.

So the first command we are going to run will create a new branch. It will prevent the above described problem. Replace name-new-branch with the name of the new branch. This name must be short, and can only contain lower case letters and numbers. Do NOT use spaces. Instead of spaces, use - (minus).

git checkout -b name-new-branch

The next command tells git that all made changes are good, and are ready to commit.

git add --all

The following command adds our change to the branch. Please replace the message with a short description of your changes. This description will be the title of the pull request we are going to make.

git commit -m "description"

The final command will push (upload) the changes to our fork. Please replace name-new-branch with the name of the branch you made a few steps above.

git push origin name-new-branch

Compare Forks and Make a Pull Request

After pushing our change to GitHub, go to your fork of the Joomla! CMS.

Informations complémentaires

Because the staging version of Joomla! can change any moment, it is very useful to have the possibility for keeping our fork up-to-date. We can do that by adding a remote to our forked project:

git remote add upstream https://github.com/joomla/joomla-cms.git

We now added a remote called "upstream". With the following command, Git will search for new contribution (commits) in the staging branch we don't have in our fork. If it found some, it will add them to our fork:

git pull upstream staging

Les modifications ne sont maintenant effectuées que sur notre fourche locale. Pour les télécharger sur GitHub, utilisez la commande suivante:

git push