mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
French translation
This commit is contained in:
Maniack Crudelis
parent
f9039620a3
commit
a774899676
6 changed files with 215 additions and 14 deletions
|
|
@ -7,6 +7,7 @@
|
|||
* [Apps wishlist](/apps_wishlist)
|
||||
* [General introduction to app packaging](/packaging_apps_start)
|
||||
* [Technical introduction to app packaging](/packaging_apps)
|
||||
* [How to use Git to package apps](/packaging_apps_git)
|
||||
* [Setting up a dev environment with VirtualBox](/packaging_apps_virtualbox)
|
||||
* [Manifest](packaging_apps_manifest)
|
||||
* [Scripts](packaging_apps_scripts)
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@
|
|||
* [Liste d'apps souhaitées par la communauté](/apps_wishlist)
|
||||
* [Introduction générale au packaging d'apps](/packaging_apps_start)
|
||||
* [Introduction technique au packaging d'apps](/packaging_apps)
|
||||
* [Comment utiliser Git pour packager les applications](/packaging_apps_git)
|
||||
* [Déployer un environnement de développement avec VirtualBox](/packaging_apps_virtualbox)
|
||||
* [Manifest](/packaging_apps_manifest)
|
||||
* [Scripts](/packaging_apps_scripts)
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ The purpose of this document is to teach you how to package an application for Y
|
|||
### Requirements
|
||||
To package an application, here are the requirements:
|
||||
* An account on a git server (e.g. [GitHub](https://github.com/)) to publish the application;
|
||||
* Basic knowledge of `git`, bash shell and other programming stuff;
|
||||
* Basic knowledge of [git](/packaging_apps_git), bash shell and other programming stuff;
|
||||
* A testing [virtual machine or a distant server](/install), or a development environement, [ynh-dev](https://github.com/yunohost/ynh-dev) or [VirtualBox](/packaging_apps_virtualbox), to package and test the package.
|
||||
|
||||
### Content
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Ce document a pour but de vous apprendre à packager une application pour YunoHo
|
|||
### Prérequis
|
||||
Pour packager une application, voici les prérequis :
|
||||
* Un compte sur un serveur git comme [GitHub](https://github.com/) pour pouvoir ensuite publier l’application ;
|
||||
* Maîtriser un minimum `git`, le Shell et d’autres notions de programmation ;
|
||||
* Maîtriser un minimum [git](/packaging_apps_git), le Shell et d’autres notions de programmation ;
|
||||
* Une [machine virtuelle ou sur un serveur distant](/install) ou un environnement de développement, [ynh-dev](https://github.com/yunohost/ynh-dev) ou [VirtualBox](/packaging_apps_virtualbox), pour packager et tester son paquet.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# How to use git to package apps
|
||||
# How to use Git to package apps
|
||||
|
||||
Git... Our dear beloved Git, which can be described also as "Goddamn Idiotic Truckload of sh*t", according to Linus.
|
||||
Be sure if you don't know git yet that you will soon agree with that description.
|
||||
Be sure if you don't know Git yet that you will soon agree with that description.
|
||||
|
||||
YunoHost and all our apps are on the git forge GitHub. Which means that if you want to work on an app, sooner or later you're going to have to deal with git.
|
||||
So let's see how to work with git to be able to contribute in the context of YunoHost.
|
||||
YunoHost and all our apps are on the Git forge GitHub. Which means that if you want to work on an app, sooner or later you're going to have to deal with Git.
|
||||
So let's see how to work with Git to be able to contribute in the context of YunoHost.
|
||||
|
||||
## Working with GitHub
|
||||
|
||||
|
|
@ -38,8 +38,7 @@ If you have the permission to write, you will just edit the file, without forkin
|
|||
#### Commit your changes
|
||||
|
||||
When you're done with your modification on the file, you can commit your changes.
|
||||
Behind that word, the idea is quite simple, you're just going to save your changes...
|
||||
|
||||
Behind that word, the idea is quite simple, you're just going to save your changes...
|
||||
<img src="/images/github_commit.png" width=100%>
|
||||
|
||||
The first field is the name of your commit, a very short sentence to explain why you did this modification.
|
||||
|
|
@ -89,7 +88,7 @@ Your repo will be moved into the organization, you don't have to remove the orig
|
|||
As we have seen, you can do a lot of things directly on GitHub.
|
||||
But when you need to edit multiple files, or when you need to work on your code on your own, it's better to work directly on your computer.
|
||||
|
||||
Before going to the hellish part of git, let's see 2 different ways to start working with git.
|
||||
Before going to the hellish part of Git, let's see 2 different ways to start working with Git.
|
||||
|
||||
#### First case: Creating a new package
|
||||
|
||||
|
|
@ -107,7 +106,7 @@ git clone https://github.com/YunoHost/example_ynh
|
|||
```
|
||||
`git clone` will download a copy of the repository. You will have the complete repository, with its branches, commits, and everything (into that apparently little `.git` directory).
|
||||
|
||||
To git clone is usually the starting point of any local work with git.
|
||||
To git clone is usually the starting point of any local work with Git.
|
||||
|
||||
*A side note though, if you expect to send your modifications back to the distant repository on GitHub, be sure to have the permission to write on this repository. Otherwise, fork before and clone your fork, on which you do have the permission.*
|
||||
|
||||
|
|
@ -144,7 +143,7 @@ If it appears that you're not on the branch you wanted to be, or you're actually
|
|||
```
|
||||
git checkout testing
|
||||
```
|
||||
*Read carefully what git says when you validate a command, do never forget that git is sneaky...*
|
||||
*Read carefully what Git says when you validate a command, do never forget that Git is sneaky...*
|
||||
|
||||
#### Git pull before anything else
|
||||
|
||||
|
|
@ -152,7 +151,7 @@ You're finally on the right branch, and ready to work.
|
|||
**Wait ! A nasty trap is waiting for you...**
|
||||
Before ending up in an inextricable situation. Start with a `git pull` to update your branch to the latest change from the distant repository.
|
||||
|
||||
*Sometimes, you will encounter an impossible situation where git is saying that you can't pull because you have local changes. But you don't care of those local modifications, you just want to get the last version of the distant branch. But git don't care about what YOU want...*
|
||||
*Sometimes, you will encounter an impossible situation where Git is saying that you can't pull because you have local changes. But you don't care of those local modifications, you just want to get the last version of the distant branch. But Git don't care about what YOU want...*
|
||||
*I have to admit that my only solution is as highly efficient as dirty... A good old `rm -r` of the repository and a `git clone`*
|
||||
|
||||
#### Let's work
|
||||
|
|
@ -160,7 +159,7 @@ Before ending up in an inextricable situation. Start with a `git pull` to update
|
|||
Eventually, you can work on your code.
|
||||
When you are finally ok with what you have done, it's time to validate your work.
|
||||
|
||||
The first step is to inform git about which file(s) to validate. To do so, we'll use `git add`
|
||||
The first step is to inform Git about which file(s) to validate. To do so, we'll use `git add`
|
||||
```
|
||||
git add my_file
|
||||
git add my_other_file and_also_this_one
|
||||
|
|
@ -182,7 +181,7 @@ To create a new branch and move to this branch, you can use `git checkout -b my_
|
|||
|
||||
#### Commit
|
||||
|
||||
To commit is simply to validate your work in git. As you can do in GitHub.
|
||||
To commit is simply to validate your work in Git. As you can do in GitHub.
|
||||
To have the same fields that you had on GitHub, with the name of the commit, and a longer explanation. You can simply use `git commit`.
|
||||
The first line, before the comments, is for the name of the commit.
|
||||
After all the comments, you can add an explanation if you want to.
|
||||
|
|
|
|||
200
packaging_apps_git_fr.md
Normal file
200
packaging_apps_git_fr.md
Normal file
|
|
@ -0,0 +1,200 @@
|
|||
# Comment utiliser Git pour packager les applications
|
||||
|
||||
Git... Notre cher Git bien-aimé, que l'on peut aussi décrire comme "Goddamn Idiotic Truckload of sh*t", selon Linus.
|
||||
Si vous ne connaissez pas encore Git, soyez sûr que vous serez bientôt d'accord avec cette description.
|
||||
|
||||
YunoHost et toutes nos applications sont sur la forge Git GitHub. Ce qui veut dire que si vous voulez travailler sur une application, tôt ou tard vous allez devoir faire face à Git.
|
||||
Alors voyons comment travailler avec Git pour pouvoir contribuer dans le contexte de YunoHost.
|
||||
|
||||
## Travailler avec GitHub
|
||||
|
||||
Commençons par la partie facile, GitHub est livré avec une interface web "facile" à utiliser.
|
||||
|
||||
*Tout d'abord, malheureusement il n'y a pas moyen de contourner ça, vous devez avoir un compte sur GitHub.*
|
||||
|
||||
#### Branches
|
||||
|
||||
Ensuite, et c'est probablement l'une des choses les plus importantes, **ne travaillez pas directement sur la branche master**.
|
||||
Désolé, il fallait que ce soit dit !
|
||||
|
||||
Les branches sont, comme l'explique GitHub, "*une version parallèle d'un dépôt. Elle est contenue dans le dépôt, mais n'affecte pas les autres branches. Elle vous permet de travailler librement sans perturber la version "live".*"
|
||||
|
||||
La branche master est la branche qui contient la version de l'application que les utilisateurs installeront et utiliseront effectivement.
|
||||
La chose habituelle à faire est de travailler à partir de la branche testing, et lorsque tout est réglé et testé, vous pouvez fusionner la branche testing dans master, afin que les utilisateurs puissent profiter de la nouvelle version de votre package.
|
||||
|
||||
Pour voir et modifier la branche actuelle, utilisez ce bouton :
|
||||
<img src="/images/github_branch.png" width=100%>
|
||||
|
||||
#### Modifier un fichier
|
||||
|
||||
Maintenant que vous êtes sur la bonne branche, voyons comment éditer un fichier sur GitHub.
|
||||
|
||||
Vous pouvez éditer n'importe quel fichier en utilisant l'icône du petit crayon :
|
||||
<img src="/images/github_edit.png" width=100%>
|
||||
|
||||
Si vous n'avez pas la permission d'écrire sur le dépôt, vous verrez (comme sur l'image) que vous allez créer un fork (nous verrons plus loin ce qu'est un fork).
|
||||
Si vous avez la permission d'écrire, vous allez simplement modifier le fichier, sans forker.
|
||||
|
||||
#### Validez vos modifications
|
||||
|
||||
Lorsque vous avez fini de modifier le fichier, vous pouvez faire un commit de vos modifications.
|
||||
Derrière ce mot, l'idée est assez simple, vous allez juste enregistrer vos modifications...
|
||||
<img src="/images/github_commit.png" width=100%>
|
||||
|
||||
Le premier champ est le nom de votre commit, une phrase très courte pour expliquer pourquoi vous avez fait cette modification.
|
||||
Le deuxième champ est un champ plus grand pour une explication plus complète, si vous en avez besoin.
|
||||
|
||||
Enfin, si vous modifiez un dépôt sur lequel vous avez la permission d'écrire, vous pouvez soit faire un commit directement sur la branche en cours, soit créer une nouvelle branche.
|
||||
Il est généralement préférable de créer une nouvelle branche, de cette façon vous gardez vos modifications sur une version *parallèle* du dépôt. Vos modifications seront discutées dans une pull request (expliquée ci-dessous) puis finalement fusionnées dans la branche d'origine.
|
||||
|
||||
#### Forker ou ne pas forker
|
||||
|
||||
Un fork est une copie d'un dépôt sur votre propre compte.
|
||||
Nous avons déjà vu que si vous n'avez pas l'autorisation d'écrire dans un dépôt, la modification d'un fichier créera automatiquement un fork.
|
||||
Comme le fork est sur votre compte, vous avez toujours la permission d'écrire dessus.
|
||||
Mais même si un fork n'est pas le véritable dépôt, mais juste une copie, un fork est toujours lié à son parent. Nous verrons plus tard que la création d'un fork est vraiment utile lors de l'ouverture d'une pull request.
|
||||
|
||||
Lorsque vous créez un nouveau package, il est courant d'utiliser l'[application d'exemple](https://github.com/YunoHost/example_ynh) comme base.
|
||||
Mais, comme vous ne voulez pas garder ce lien vers l'application d'exemple, vous ne devez pas forker l'application d'exemple. Vous la clonerez plutôt.
|
||||
Malheureusement, cloner une application est un peu plus compliqué sur GitHub. Nous verrons plus tard comment cloner vers un dépôt local à la place.
|
||||
|
||||
Nous avons vu comment éditer un fichier, et comment cela peut forker l'application.
|
||||
Mais, lorsque vous voulez éditer plusieurs fichiers, l'interface GitHub n'est pas vraiment la meilleure solution. Dans une telle situation, vous préférez cloner le dépôt et travailler sur un dépôt local.
|
||||
Il se peut que vous deviez tout de même forker sur votre propre compte pour pouvoir enregistrer vos modifications si vous n'avez pas les autorisations sur le dépôt distant.
|
||||
|
||||
#### Pull request
|
||||
|
||||
Après avoir effectué vos commits, que ce soit sur une branche ou un fork, vous souhaitez proposer vos modifications pour qu'elles soient intégrées dans le dépôt principal, ou dans la branche d'origine.
|
||||
Pour ce faire, vous allez créer une pull request. GitHub vous demande généralement directement si vous souhaitez le faire.
|
||||
Sinon, vous trouverez le bouton de création d'une pull request juste ici :
|
||||
<img src="/images/github_pull_request.png" width=100%>
|
||||
|
||||
Lors de la création d'une pull request à partir d'un fork, pour faciliter le travail de révision du code, **ne jamais** décocher la case *Allow edits from maintainers*. Cette option permet simplement aux mainteneurs du dépôt d'origine de modifier directement votre travail.
|
||||
|
||||
#### Organisation YunoHost-Apps
|
||||
|
||||
Conformément à la [YEP 1.7](https://github.com/YunoHost/doc/blob/master/packaging_apps_guidelines.md#yep-17), votre application doit être intégrée à l'organisation YunoHost-Apps, mais si vous n'avez jamais contribué à une application auparavant ou si vous n'avez jamais eu d'application dans cette organisation, vous n'en aurez peut-être pas l'autorisation.
|
||||
|
||||
Tout d'abord, vous devez avoir la permission d'écrire dans l'organisation, pour ce faire, demandez au groupe Apps sur le salon xmpp Apps.
|
||||
|
||||
Pour transférer votre application sur l'organisation YunoHost-Apps, allez dans votre dépôt et dans l'onglet *Settings*.
|
||||
En bas de la page, vous trouverez *Transfer ownership*.
|
||||
Dans le champ *New owner’s GitHub username or organization name*, tapez *YunoHost-Apps*.
|
||||
Votre dépôt sera déplacé dans l'organisation, vous n'avez pas besoin de supprimer le dépôt d'origine.
|
||||
|
||||
|
||||
## Travailler avec Git en local
|
||||
|
||||
Comme nous l'avons vu, vous pouvez faire beaucoup de choses directement sur GitHub.
|
||||
Mais lorsque vous devez modifier plusieurs fichiers, ou lorsque vous devez travailler sur votre code de votre côté, il est préférable de travailler directement sur votre ordinateur.
|
||||
|
||||
Avant d'aller dans la partie infernale de Git, voyons 2 façons différentes de commencer à travailler avec Git.
|
||||
|
||||
#### Premier cas : Créer un nouveau package
|
||||
|
||||
Vous avez découvert, choqué, que la merveilleuse application que vous aimez utiliser tous les jours n'a pas encore son package YunoHost. Et parce que vous êtes sympa, vous avez décidé de créer vous-même le package, pour que tout le monde puisse apprécier cette application.
|
||||
Quelle bonne idée !
|
||||
|
||||
Le mieux est de commencer par l'[application d'exemple] (https://github.com/YunoHost/example_ynh). Mais comme nous l'avons déjà expliqué, vous ne voulez pas forker, parce que si vous le faites, vous allez garder ce lien vers l'application d'exemple et c'est vraiment ennuyeux.
|
||||
Donc, vous allez le faire différemment. Vous allez cloner !
|
||||
|
||||
##### git clone
|
||||
|
||||
Pour cloner, vous allez faire :
|
||||
```
|
||||
git clone https://github.com/YunoHost/example_ynh
|
||||
```
|
||||
`git clone` téléchargera une copie du dépôt. Vous aurez le dépôt complet, avec ses branches, ses commits, et tout le reste (dans cet apparent petit répertoire `.git`).
|
||||
|
||||
git clone est généralement le point de départ de tout travail local avec Git.
|
||||
|
||||
*Toutefois, si vous comptez envoyer vos modifications sur le dépôt distant sur GitHub, assurez-vous d'avoir les droits d'écriture sur ce dépôt. Sinon, forkez avant et clonez votre fork, pour lequel vous avez la permission.*
|
||||
|
||||
##### Mon tout nouveau package, suite
|
||||
|
||||
Dans le contexte d'un nouveau package, vous devrez également créer un dépôt sur GitHub pour y mettre votre package. Ce qui n'est pas plus compliqué qu'un gros bouton vert *New*.
|
||||
Ne vous embêtez pas avec des README, .gitignore ou licence. Créez simplement le dépôt lui-même.
|
||||
vous pouvez maintenant cloner ce nouveau dépôt avec Git.
|
||||
<img src="/images/github_create_new_repo.png" width=100%>
|
||||
|
||||
Vous disposez maintenant de 2 dépôts clonés sur votre ordinateur.
|
||||
Copiez tous les fichiers de l'application example_ynh, **excepté le répertoire .git** (vous voulez juste les fichiers eux-mêmes) dans votre nouveau package.
|
||||
|
||||
*Si vous le souhaitez, vous pouvez supprimer l'application example_ynh. Nous n'en avons plus besoin.*
|
||||
|
||||
Vous êtes prêt à travailler sur votre nouveau package !
|
||||
|
||||
#### Deuxième cas : Travailler localement sur un dépôt
|
||||
|
||||
Vous disposez déjà d'un dépôt, mais ce que vous voulez, c'est travailler localement, de sorte que vous puissiez modifier plusieurs fichiers.
|
||||
Il vous suffit de cloner le dépôt, le répertoire .git est le lien vers le dépôt distant. Rien d'autre à faire qu'un `git clone`.
|
||||
|
||||
#### Branches
|
||||
|
||||
Vous avez bien votre copie local du dépôt, mais comme vous avez lu attentivement cette documentation jusque-là, vous savez que vous devez vous assurer d'être sur la branche testing avant de commencer à travailler.
|
||||
|
||||
Pour voir les branches, et savoir sur quelle branche vous êtes réellement, alors que vous êtes dans le répertoire de votre dépôt, tapez `git branch`.
|
||||
La branche courante est mise en évidence et précédée d'un "*".
|
||||
|
||||
#### git checkout
|
||||
|
||||
S'il apparaît que vous n'êtes pas sur la branche où vous vouliez être, ou que vous êtes en fait sur master (ce qui est mal !), vous pouvez passer à une autre branche avec `git checkout`.
|
||||
```
|
||||
git checkout testing
|
||||
```
|
||||
*Lisez attentivement ce que Git dit quand vous validez une commande, n'oubliez jamais que Git est sournois...*
|
||||
|
||||
#### git pull avant tout
|
||||
|
||||
Vous êtes enfin dans la bonne branche, et prêt à travailler.
|
||||
**Attendez ! Un vilain piège vous attend...**
|
||||
Avant de vous retrouver dans une situation inextricable. Commencez par un `git pull` pour mettre à jour votre branche avec les derniers changements du dépôt distant.
|
||||
|
||||
*Parfois, vous rencontrerez une situation impossible où Git vous dira que vous ne pouvez pas pull parce que vous avez des changements locaux. Mais vous ne vous souciez pas de ces modifications locales, vous voulez juste obtenir la dernière version de la branche distante. Mais Git ne se soucie pas de ce que VOUS voulez...*
|
||||
*Je dois admettre que ma seule solution est aussi efficace que sale... Un bon vieux `rm -r` du dépôt et un `git clone`*
|
||||
|
||||
#### Il est temps de travailler
|
||||
|
||||
Vous pouvez finalement travailler sur votre code.
|
||||
Lorsque vous êtes enfin d'accord avec ce que vous avez fait, il est temps de valider votre travail.
|
||||
|
||||
La première étape consiste à informer Git sur le(s) fichier(s) à valider. Pour ce faire, nous utiliserons `git add`.
|
||||
```
|
||||
git add mon_fichier
|
||||
ajouter mon_autre_fichier et_aussi_celui_ci
|
||||
```
|
||||
Si vous souhaitez valider tous votre travail, vous pouvez aussi simplement faire
|
||||
```
|
||||
git add --all
|
||||
```
|
||||
|
||||
Pour vérifier l'état actuel de votre validation, vous pouvez utiliser `git status`. Il vous montrera quels fichiers seront inclus dans votre commit, et quels fichiers sont modifiés, mais pas encore inclus.
|
||||
`git status -v` vous indiquera également quelle partie des fichiers est modifiée. Une bonne façon de s'assurer que vous n'avez pas fait d'erreur avant de faire un commit.
|
||||
|
||||
#### git checkout -b
|
||||
|
||||
Avant de faire un commit, ou après, ou avant de commencer à travailler. Quand vous en avez envie !
|
||||
Vous devriez envisager d'ajouter votre travail à une branche séparée, de cette façon, il sera facile de créer une pull request dans la branche testing et de discuter avec les autres packagers de ce que vous suggérez de changer.
|
||||
|
||||
Pour créer une nouvelle branche et passer à cette branche, vous pouvez utiliser `git checkout -b my_new_branch`.
|
||||
|
||||
#### Commit
|
||||
|
||||
Faire un commit, c'est simplement valider son travail dans Git. Comme vous pouvez le faire dans GitHub.
|
||||
Pour avoir les mêmes champs que vous aviez sur GitHub, avec le nom du commit, et une explication plus longue. Vous pouvez simplement utiliser `git commit`.
|
||||
La première ligne, avant les commentaires, est pour le nom du commit.
|
||||
Après tous les commentaires, vous pouvez ajouter une explication si vous le souhaitez.
|
||||
|
||||
Si vous voulez faire un commit avec seulement un nom pour votre commit, vous pouvez utiliser une simple commande :
|
||||
```
|
||||
git commit -m "My commit name"
|
||||
```
|
||||
|
||||
#### Push vers le dépôt distant
|
||||
|
||||
Vos modifications sont validées, mais uniquement sur votre clone local du dépôt. Maintenant, vous devez renvoyer ces modifications sur le dépôt distant sur GitHub.
|
||||
Pour ce faire, vous devez savoir quelle est votre branche actuelle. (Si vous ne le savez pas, `git branch` vous donnera cette information).
|
||||
Ensuite, vous pouvez git push
|
||||
```
|
||||
git push -u origin BRANCH_NAME
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue