diff --git a/contributordoc_fr.md b/contributordoc_fr.md index 80611ac9..6e5bd3b0 100644 --- a/contributordoc_fr.md +++ b/contributordoc_fr.md @@ -9,7 +9,7 @@ * [Développer avec Docker](/docker_fr) * [Builder OpenResty (serveur Web) pour Raspberry Pi](/build_openresty_fr) * [Présentation du fonctionnement de YunoHost](/package_list_fr) - * [Se créer un environnement de développement](/dev_fr) + * [Se créer un environnement de développement](/ynh_dev_fr) * Documentation * [Création d’un compte pour l’édition de la documentation](/accounting_fr) - * [Écrire de la documentation](/write_documentation_fr) \ No newline at end of file + * [Écrire de la documentation](/write_documentation_fr) diff --git a/dev.md b/dev.md index 9bbc7536..f16ac4f6 100644 --- a/dev.md +++ b/dev.md @@ -1,29 +1,34 @@ -# Contributing to the Yunohost core +## Contributing to the Yunohost core -You wish to implement a new feature in the Yunohost core, but don't know how to +You wish to add a new feature in the Yunohost core, but don't know how to proceed ? This guide takes you through the various steps of the development and contribution process. -If you're looking for stuff to implement or fix, the bugtracker is +If you're looking for stuff to implement or fix, the bug-tracker is [here](https://dev.yunohost.org/issues/) ! -## Setting up a development environment +**Come say hi to us in the [dev chatroom](xmpp:dev@conference.yunohost.org?join)** ! If you don't have an XMPP client, you can join using the widget at the bottom right of this page. + +### Setting up a development environment - **Use [ynh-dev](https://github.com/YunoHost/ynh-dev)** (see the README) to setup a development environment - locally in a virtual machine, or on a VPS. - This will setup a working Yunohost instance, using git repositories and - symlinks. That way, you will be able to edit files, test your changes, commit - stuff and push/pull directly from your development environment. + This will setup a working Yunohost instance, using directly the git repositories + (with symlinks). That way, you will be able to edit files, test your changes in real + time, commit stuff and push/pull directly from your development environment. -- Implement and test your feature. Depending on what you want to develop, you +- **Implement and test your feature**. Depending on what you want to develop, you will want to : - - **Python/CLI core** : work in `/vagrant/yunohost/`, i.e. the Python/CLI core + - **Python/CLI core** : work in `/vagrant/yunohost/` - **Web administration interface** : work in `/vagrant/yunohost-admin/` - - You can also work on the other projects (SSOwat, moulinette) in similar ways + - You can also work on the other projects on which Yunohost is built + (SSOwat, moulinette) in similar ways -## Developping on the Yunohost Python/CLI core +### Working on the Yunohost Python/CLI core -- Work in `/vagrant/yunohost/` +- Work in `/vagrant/yunohost/`. + +- Run `/vagrant/ynh-dev use-git yunohost`. - The actionsmap file (`data/actionsmap/yunohost.yml`) defines the various categories, actions and arguments of the yunohost CLI. Define how you want @@ -38,33 +43,29 @@ If you're looking for stuff to implement or fix, the bugtracker is `domain_add(domainName)` in `domain.py`, with the argument `domainName` equal to `"some.domain.tld"`. -#### Helpers / coding style +##### Helpers / coding style - To handle exceptions, you should raise some `MoulinetteError()` - To help with internationalizing the messages, use `m18n.n('some-message-id')` and put your string in `locales/en.json`. You can also put arguments and use them in the string with `{{some-argument:s}}`. Don't edit other locales files, - only the en.json ! + this will be done using [weblate](https://translate.yunohost.org/) ! - Yunohost tries to follow the [pep8](http://pep8.org/) coding style. Tools exist to automatically check conformity. - Name of "private" functions should start with a `_` -#### Don't forget +##### Don't forget - (Might not be necessary anymore) Each time you edit the actionsmap, you should force the refresh of the cache with `rm /var/cache/moulinette/actionsmap/yunohost.pkl` -## Adding stuff to the Yunohost web administration interface +### Working on the Yunohost web administration interface -- Work in `/vagrant/yunohost-admin/src/` - -- Make sure the web admin interface of your development environment works, by - opening `https://domain.tld/yunohost/admin`. If not, run `npm install` and - `npm run build` in `yunohost-admin/src/`. [Not sure about this, to be checked] +- Work in `/vagrant/yunohost-admin/src/`. - Run `/vagrant/ynh-dev use-git yunohost-admin`. It launches gulp, such as each time you modify sources, it recompiles the code and you can use it by @@ -89,14 +90,14 @@ If you're looking for stuff to implement or fix, the bugtracker is `{{some-variable}}`, which will be replaced when building/accessing the page. It is also possible to have conditions using the [handlebars.js](http://handlebarsjs.com) syntax : ```{{#if - some-variable}}

Some conditionnal HTML code here !

{{/if}}``` + some-variable}}

Some conditional HTML code here !

{{/if}}``` - For internationalized strings, use `y18n.t('some-string-code')` in the javascript, or `{{t 'some-string-code'}}` in the HTML template, and put your - string in `locales/en.json`. Don't edit other locales files, only the - en.json ! + string in `locales/en.json`. Don't edit other locales files, + this will be done using [weblate](https://translate.yunohost.org/) ! -#### Don't forget +##### Don't forget - Each time you edit the actionsmap, you should restart the yunohost-api : ```service yunohost-api restart``` @@ -106,19 +107,49 @@ If you're looking for stuff to implement or fix, the bugtracker is the javascript and/or html (so each time you edit something in `js` or `views`). -## Your feature is working and you want it to be integrated in Yunohost +### Your feature is ready and you want it to be integrated in Yunohost - Fork the relevant repo on Github, and commit stuff to a new branch. We recommend to name the branch with the following convention : - - For an enhancement or new feature : `enh-REDMINETICKET-name-of-feature`, where - REDMINETICKET is optional and is the id of a corresponding ticket on RedMine. - - For a bugfix fix-IDREDMINETICKET-description-of-fix", where - REDMINETICKET is optional and is the id of a corresponding ticket on RedMine. + - For an enhancement or new feature : `enh-REDMINETICKET-name-of-feature` + - For a bugfix `fix-REDMINETICKET-description-of-fix` + - `REDMINETICKET` is optional and is the id of a corresponding ticket on RedMine. -- Once you're ready, open a Pull Request (PR) on Github. Please include "[fix]" or - "[enh]" at the beginning of the title of your PR. +- Once you're ready, open a Pull Request (PR) on Github. Please include `[fix]` or + `[enh]` at the beginning of the title of your PR. - After reviewing, testing and validation by other contributors, your branch should be merged in `testing` (?) ! + + + + diff --git a/dev_fr.md b/dev_fr.md index fe8f99a9..4c91094e 100644 --- a/dev_fr.md +++ b/dev_fr.md @@ -1,91 +1,164 @@ -## Créer un environnement de développement +## Contribuer au coeur de Yunohost -
-Attention : cette page de documentation n’est plus à jour. Merci de vous référer à la [documentation du dépôt](https://github.com/YunoHost/ynh-dev). -
+Vous souhaitez ajouter une nouvelle fonctionnalité au coeur de Yunohost, mais ne +savez pas comment procéder ? Ce guide parcours les étapes du développement et du +processus de contribution. -Ce document a pour but de donner les clés pour créer un environnement de développement correct afin de développer sur le cœur de YunoHost. Il peut également vous permettre de tester vos applications que ce soit avec les versions `stable`, `testing`, `unstable` ou même des versions customisées issues des branches des dépôts. +Si vous chercher quelque chose à implémenter ou un bug à réparer, le +bug tracker est [ici](https://dev.yunohost.org/issues/) ! -### Installation de l’environnement de développement -#### Installation du système de virtualisation -Installer, avec le gestionnaire de paquet de votre système d’exploitation, Vagrant. +**Venez dire coucou sur le [salon de +dev](xmpp:dev@conference.yunohost.org?join)** ! Si vous n'avez pas de client +XMPP, vous devriez pouvoir vous connecter à l'aide du widget en bas de la page. -```bash -# Debian, Ubuntu, Mint -sudo apt-get install vagrant -# Fedora -sudo dnf install vagrant -``` +### Mettre en place un environnement de développement -#### Télécharger `ynh-dev` -
-Attention : Cette partie est en cours de rédaction. La ligne de commande `ynh-dev` vient juste d’être créée il est possible qu’il y ait des manques. -
+- **Utilisez [ynh-dev](https://github.com/YunoHost/ynh-dev)** (voir le README) + pour mettre en place un environnement de développement - en local sur une + machine virtuel, ou bien sur un VPS. + Ceci installera une instance fonctionelle de Yunohost, en utilisant + directement les dépôts git à l'aide de liens symboliques. De cette facon, il + vous sera possible de modifier les fichiers, de tester les changements en + temps réel, et de commiter et push/pull directement depuis cet environnement. -Une ligne de commande `ynh-dev` a été créée afin de simplifier la gestion de votre environnement de développement. +- **Implémentez et testez votre fonctionnalité**. Suivant ce sur quoi vous + voulez travailler : + - **Coeur Python/ligne de comande** : allez dans `/vagrant/yunohost/` + - **Interface d'administration web** : allez dans `/vagrant/yunohost-admin/` + - Vous pouvez aussi travailler sur les autres projets liés sur lesquels + s'appuie Yunohost (SSOwat, moulinette) de facon similaire. -```bash -wget https://raw.githubusercontent.com/yunohost/ynh-dev/master/ynh-dev -chmod u+x ynh-dev -``` -Pour créer votre environnement, commencez par faire un `create-env` -```bash -./ynh-dev create-env ~/project/my/yunohost/env -``` -Cette sous commande va cloner les dépôts principaux au fonctionnement de YunoHost et les positionner en `unstable`. Si vous avez vos propres fork, vous pouvez ensuite faire ce qu’il faut pour changer l’origine et le remote repository. +### Travailler sur le coeur Python / ligne de commande -#### Usage -##### Lancer un container -Positionner vous dans votre environnement, puis créer et entrer dans une vm à l’aide de `ynh-dev run` -```bash -cd ~/project/my/yunohost/env -./ynh-dev run exemple.local stable8 -root@yunohost:/# cd yunohost -root@yunohost:/yunohost/# ls -Dockerfile LICENSE README.md SSOwat apps backup moulinette ynh-dev yunohost yunohost-admin yunohost-vagrant -``` +- Allez dans `/vagrant/yunohost/`. -##### Mettre à jour un container -Si la vm n’est pas à jour lancez un `ynh-dev upgrade` : -```bash -root@yunohost:/yunohost/# ./ynh-dev upgrade -``` +- Executez `/vagrant/ynh-dev use-git yunohost`. -##### Déployer les sources présentes dans votre environnement -Pour déployer les sources se trouvant dans votre environnement de développement faites : -```bash -root@yunohost:/yunohost/# ./ynh-dev deploy -``` +- Le fichier actionsmap (`data/actionsmap/yunohost.yml`) défini les différentes + catégories, actions et arguments de la ligne de commande Yunohost. Choisissez + comment vous voulez que les utilisateurs utilise votre fonctionnalité, et + ajoutez/éditez les catégories, actions et arguments correspondants. Par + exemple, dans `yunohost domain add some.domain.tld`, la catégorie est + `domain`, l'action est `add` et `some.domain.tld` est un argument. -
-Attention : pour yunohost-admin vous devez avoir compilé le js avec gulp au préalable -
+- Moulinette va automatiquement faire le lien entre les commandes de + l'actionsmap et les fonctions python (ainsi que leurs arguments) dans + `src/yunohost/`. Par exemple, `yunohost domain add some.domain.tld` + déclenchera un appel de `domain_add(domainName)` dans `domain.py`, avec l'argument + `domainName` qui vaudra `"some.domain.tld"`. -
-Note : vous pouvez sélectionner les paquets à déployer exemple : `./ynh-dev deploy yunohost yunohost-admin` -
+##### Helpers / style de code -##### Lancer la postinstall -Avec VirtualBox/Vagrant -```bash -root@yunohost:/yunohost/# yunohost tools postinstall -``` +- Pour gérer les exceptions, il existe un type `MoulinetteError()` -##### Récupérer l’IP de la vm et paramétrer son `/etc/hosts` -si vous ne connaissez pas l’IP de votre vm : -```bash -root@yunohost:/yunohost/# ./ynh-dev ip -172.17.0.1 -``` +- Pour aider avec l'internationalisation des messages, utilisez `m18n.n('some-message-id')` + et mettez le message correspondant dans `locales/en.json`. Vous pouvez aussi + utiliser des arguments pour construire les messages, avec `{{some-argument:s}}`. + Ne modifiez pas de fichiers de locales autres que en.json, la traduction sera + faite avec [weblate](https://translate.yunohost.org/) ! -Pour tester dans votre navigateur vous pouvez modifier votre fichier `/etc/hosts` afin de faire pointer votre domaine sur la bonne adresse IP. Par exemple en y ajoutant une ligne semblable à celle-ci : -```bash -172.17.0.1 exemple.local -``` +- Yunohost essaye de suivre le style de code [pep8](http://pep8.org/). Des + outils existent pour vérifier automatiquement la conformité du code. + +- Mettre un `_` devant les noms des fonctions "privées". + +##### N'oubliez pas + +- (Peut-être plus nécessaire) À chaque fois que vous modifiez l'actionsmap, il + faut forcer le rafraichissement du cache avec : + `rm /var/cache/moulinette/actionsmap/yunohost.pkl` + +### Travailler sur l'interface d'administration web + +- Allez dans `/vagrant/yunohost-admin/src/`. + +- Executez `/vagrant/ynh-dev use-git yunohost-admin`. Ceci lance gulp, de sorte + à ce que à chaque fois que vous modifiez les sources, il recompilera le code + (js) et vous pourrez voir les changements dans le navigateur web (Ctrl+F5). + Pour stopper la commande, faites simplement Ctrl+C. + +- L'interface web utilise une API pour communiquer avec Yunohost. Les + commandes/requêtes de l'API sont également définie dans l'actionsmap. Par + exemple, accéder à la page ```https://domain.tld/yunohost/api/users``` + corresponds à une requete `GET /domains` vers l'API yunohost. Cette requete + est mappée sur `user_list()`. Accéder à cette URL devrait afficher le json + retourné par cette fonction. Les requetes `GET' sont typiquement destinés à + demander de l'information au serveur, tandis que les requetes `POST` sont + destinées à demander au serveur de modifier/changer des informations ou de + réaliser des actions. + +- `js/yunohost/controllers` contiens les parties javascript, et défini quelles + requêtes faire à l'API pendant le chargement d'une page donnée de l'interface, + et comment traîter les données récupérées pour générer la page, en utilisant + des templates. + +- `views` contiens les templates des pages de l'interface. Dans le template, + les données venant du javascript peuvent êtres utilisées avec la syntaxe + `{{some-variable}}`, qui sera remplacée pendant la construction de la page. + Il est également possible d'avoir des conditions avec la syntaxe + d'[handlebars.js](http://handlebarsjs.com) : ```{{#if + some-variable}}

du HTML conditionnel ici !

{{/if}}``` + +- Pour l'internationalisation des messages, utilisez `y18n.t('some-string-code')` + dans le javascript, ou `{{t 'some-string-code'}}` dans le template HTML, et + mettez votre message dans `locales/en.json`. Ne modifiez pas de fichiers de + locales autres que en.json, la traduction sera faite avec + [weblate](https://translate.yunohost.org/) ! + +##### N'oubliez pas + +- À chaque modification de l'actionsmap, il faut redémarrer l'API yunohost : + ```service yunohost-api restart``` + (Il faudra retaper le mot de passe administrateur dans l'interface web) + +- Il faudra peut-être régulièrement forcer le rafraichissement du cache + navigateur pour propager correctement le javascript et/ou HTML (à chaque fois + que l'on change quelque chose dans `js` ou `views`, donc). + + +### Votre fonctionnalité est prête et vous souhaitez qu'elle soit intégrée dans Yunohost + +- Forkez le dépòt correspondant sur Github, et commitez votre changements dans + une nouvelle branche, Il est recommandé de nommer la branche avec la + convention : + - Pour une nouvelle fonctionnalité ou amélioration : `enh-TICKETREDMINE-description-fonctionnalité` + - Pour une correction de bug : `fix-REDMINETICKET-description-correctif` + - `TICKETREDMINE` est optionnel et correspond au numéro du ticket sur RedMine + +- Une fois prêt, ouvrez une Pull Request (PR) sur Github. De préférence, inclure + `[fix]` ou `[enh]` au début du titre de la PR. + +- Après relecture, test et validation par les autres contributeurs, votre + branche sera mergée dans `testing` (?) ! + + + -##### Déployer les sources au fur et à mesure des modifications -```bash -root@yunohost:/yunohost/# ./ynh-dev watch -``` -Astuce : dans le cas de modification sur yunohost-admin, cette commande est très pratique couplée avec un `gulp watch` sur la machine hôte. diff --git a/sitemap.md b/sitemap.md index 333e5d81..21b98050 100644 --- a/sitemap.md +++ b/sitemap.md @@ -80,16 +80,18 @@ * [Contributor guide](/contribute) * Developement - * [Package new application](/packaging_apps) - * [Manifest](packaging_apps_manifest_en) - * [Scripts](packaging_apps_scripts_en) - * [Arguments management](packaging_apps_arguments_management_en) - * [Nginx configuration](packaging_apps_nginx_conf_en) - * [Multi-instance](packaging_apps_multiinstance_en) - * [Helpers](packaging_apps_helpers_en) - * [Trap usage](packaging_apps_trap_fr) - * [Applications in progress](/apps_in_progress_en) - * [Wishlist of applications](/apps_wishlist_en) + * Applications + * [Package new application](/packaging_apps) + * [Manifest](packaging_apps_manifest_en) + * [Scripts](packaging_apps_scripts_en) + * [Arguments management](packaging_apps_arguments_management_en) + * [Nginx configuration](packaging_apps_nginx_conf_en) + * [Multi-instance](packaging_apps_multiinstance_en) + * [Helpers](packaging_apps_helpers_en) + * [Trap usage](packaging_apps_trap_fr) + * [Applications in progress](/apps_in_progress_en) + * [Wishlist of applications](/apps_wishlist_en) + * [Contributing to the Yunohost core](/dev) * [Creation of system packages](/build_system_en) * [Creation of Debian packages](/build_packages_en) * [Create an ARM board image](/build_arm_image_en) diff --git a/sitemap_fr.md b/sitemap_fr.md index 816cf16d..6d81cc79 100644 --- a/sitemap_fr.md +++ b/sitemap_fr.md @@ -90,7 +90,7 @@ * [Guide du contributeur](/contribute_fr) * Développement - * [Créer un environnement de développement](dev_fr) + * [Créer un environnement de développement](ynh_dev_fr) * [Présentation du fonctionnement de YunoHost](/package_list_fr) * Applications : * [Packager des applications](/packaging_apps_fr) @@ -103,6 +103,7 @@ * [Usage de trap](packaging_apps_trap_fr) * [Packages d’applications en cours de développement](/apps_in_progress_fr) * [Liste de proposition d’applications](/apps_wishlist_fr) + * [Contribuer au coeur de Yunohost](/dev_fr) * [Création de paquets système](/build_system_fr) * [Création de paquets Debian](/build_packages_fr) * [Créer une image pour carte ARM](/build_arm_image_en) diff --git a/ynh_dev_fr.md b/ynh_dev_fr.md new file mode 100644 index 00000000..fe8f99a9 --- /dev/null +++ b/ynh_dev_fr.md @@ -0,0 +1,91 @@ +## Créer un environnement de développement + +
+Attention : cette page de documentation n’est plus à jour. Merci de vous référer à la [documentation du dépôt](https://github.com/YunoHost/ynh-dev). +
+ +Ce document a pour but de donner les clés pour créer un environnement de développement correct afin de développer sur le cœur de YunoHost. Il peut également vous permettre de tester vos applications que ce soit avec les versions `stable`, `testing`, `unstable` ou même des versions customisées issues des branches des dépôts. + +### Installation de l’environnement de développement +#### Installation du système de virtualisation +Installer, avec le gestionnaire de paquet de votre système d’exploitation, Vagrant. + +```bash +# Debian, Ubuntu, Mint +sudo apt-get install vagrant +# Fedora +sudo dnf install vagrant +``` + +#### Télécharger `ynh-dev` +
+Attention : Cette partie est en cours de rédaction. La ligne de commande `ynh-dev` vient juste d’être créée il est possible qu’il y ait des manques. +
+ +Une ligne de commande `ynh-dev` a été créée afin de simplifier la gestion de votre environnement de développement. + +```bash +wget https://raw.githubusercontent.com/yunohost/ynh-dev/master/ynh-dev +chmod u+x ynh-dev +``` +Pour créer votre environnement, commencez par faire un `create-env` +```bash +./ynh-dev create-env ~/project/my/yunohost/env +``` +Cette sous commande va cloner les dépôts principaux au fonctionnement de YunoHost et les positionner en `unstable`. Si vous avez vos propres fork, vous pouvez ensuite faire ce qu’il faut pour changer l’origine et le remote repository. + +#### Usage +##### Lancer un container +Positionner vous dans votre environnement, puis créer et entrer dans une vm à l’aide de `ynh-dev run` +```bash +cd ~/project/my/yunohost/env +./ynh-dev run exemple.local stable8 +root@yunohost:/# cd yunohost +root@yunohost:/yunohost/# ls +Dockerfile LICENSE README.md SSOwat apps backup moulinette ynh-dev yunohost yunohost-admin yunohost-vagrant +``` + +##### Mettre à jour un container +Si la vm n’est pas à jour lancez un `ynh-dev upgrade` : +```bash +root@yunohost:/yunohost/# ./ynh-dev upgrade +``` + +##### Déployer les sources présentes dans votre environnement +Pour déployer les sources se trouvant dans votre environnement de développement faites : +```bash +root@yunohost:/yunohost/# ./ynh-dev deploy +``` + +
+Attention : pour yunohost-admin vous devez avoir compilé le js avec gulp au préalable +
+ +
+Note : vous pouvez sélectionner les paquets à déployer exemple : `./ynh-dev deploy yunohost yunohost-admin` +
+ +##### Lancer la postinstall +Avec VirtualBox/Vagrant +```bash +root@yunohost:/yunohost/# yunohost tools postinstall +``` + +##### Récupérer l’IP de la vm et paramétrer son `/etc/hosts` +si vous ne connaissez pas l’IP de votre vm : +```bash +root@yunohost:/yunohost/# ./ynh-dev ip +172.17.0.1 +``` + +Pour tester dans votre navigateur vous pouvez modifier votre fichier `/etc/hosts` afin de faire pointer votre domaine sur la bonne adresse IP. Par exemple en y ajoutant une ligne semblable à celle-ci : +```bash +172.17.0.1 exemple.local +``` + +##### Déployer les sources au fur et à mesure des modifications +```bash +root@yunohost:/yunohost/# ./ynh-dev watch +``` + +Astuce : dans le cas de modification sur yunohost-admin, cette commande est très pratique couplée avec un `gulp watch` sur la machine hôte.