diff --git a/contribute.md b/contribute.md index 4e95f97e..e8dfcb6b 100644 --- a/contribute.md +++ b/contribute.md @@ -47,7 +47,7 @@ Our support relies on contributors like you. Just come to [the XMPP chatroom](/s You can involve in the YunoHost's development regardless of your skill. Sysadmins, web developers, designers and pythonists are welcome!
-A [development chat room](xmpp:dev@conference.yunohost.org?join) and a mailing-list is available. +Learn [how to contribute](/dev), and join us on the [development chat room](xmpp:dev@conference.yunohost.org?join) and the mailing-list. diff --git a/contribute_fr.md b/contribute_fr.md index 8ec24b6f..0382d0e3 100644 --- a/contribute_fr.md +++ b/contribute_fr.md @@ -45,7 +45,7 @@ Notre support est communautaire et s’appuie sur des contributeurs comme vous.
Vous pouvez vous impliquer dans le développement de YunoHost peu importe votre niveau. Administrateurs système, développeurs web, designers et pythonistes sont les bienvenus.
-Une mailing-list est également disponible. +Découvrez [comment contribuer](/dev_fr), et rejoignez-nous sur le [salon de discussion](xmpp:dev@conference.yunohost.org?join) et la mailing-list !
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 new file mode 100644 index 00000000..1d677afc --- /dev/null +++ b/dev.md @@ -0,0 +1,155 @@ +## Contributing to the YunoHost core + +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 bug-tracker is +[here](https://dev.yunohost.org/issues/) ! + +**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 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 + will want to : + - **Python/CLI core** : work in `/vagrant/yunohost/` + - **Web administration interface** : work in `/vagrant/yunohost-admin/` + - You can also work on the other projects on which YunoHost is built + (SSOwat, moulinette) in similar ways + +### Working on the YunoHost Python/CLI core + +- 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 + users to use your feature, and add/edit the corresponding categories, actions + and arguments. For example in `yunohost domain add some.domain.tld`, the + category is `domain`, the action is `add`, and `some.domain.tld` is an + argument. + +- Moulinette will automatically map commands in the actionsmap to python + functions (and their arguments) located in `src/yunohost/`. For example, typing + `yunohost domain add some.domain.tld` will call the function + `domain_add(domainName)` in `domain.py`, with the argument `domainName` equal + to `"some.domain.tld"`. + +##### 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, + 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 + +- (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` + +### Working on the YunoHost web administration interface + +- 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 + refreshing (Ctrl+F5) your web administration. To stop the command, just do Ctrl+C. + +- The web interface uses the API to interact with YunoHost. The API + commands/requests are also defined via the actionsmap. For instance, accessing + the page ```https://domain.tld/yunohost/api/users``` corresponds to a `GET + /users` requests on the YunoHost API. It is mapped to the function + `user_list()`. Accessing the URL should display the json returned by this + function. 'GET' requests are typically meant to ask information to the server. + 'POST' requests are meant to ask the server to edit/change some information, + or to execute some actions. + +- `js/yunohost/controllers` contains the javascript parts, + and define which requests to make to the API when loading a specific page of + the interface, and how to process the data to generate the page, using + templates. + +- `views` contains the various templates for the pages of the interface. In the + template, data coming from the javascript part can be used with the syntax + `{{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 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, + this will be done using [weblate](https://translate.yunohost.org/) ! + +##### Don't forget + +- Each time you edit the actionsmap, you should restart the yunohost-api : + ```service yunohost-api restart``` + (You'll need to retype your admin password in the web interface) + +- You might need to force-clear the cache of your browser sometimes to refresh + the javascript and/or html (so each time you edit something in `js` or `views`). + + +### 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` + - 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. + +- 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..e623d853 100644 --- a/dev_fr.md +++ b/dev_fr.md @@ -1,91 +1,164 @@ -## Créer un environnement de développement +## Contribuer au cœur 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 cœur 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 façon, 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 : + - **Cœur 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 façon 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 cœur 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éfinit les différentes + catégories, actions et arguments de la ligne de commande YunoHost. Choisissez + comment vous voulez que les utilisateurs utilisent 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 rafraîchissement du cache avec : + `rm /var/cache/moulinette/actionsmap/yunohost.pkl` + +### Travailler sur l'interface d'administration web + +- Allez dans `/vagrant/yunohost-admin/src/`. + +- Exécutez `/vagrant/ynh-dev use-git yunohost-admin`. Ceci lance gulp, de sorte + qu'à 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éfinies dans l'actionsmap. Par + exemple, accéder à la page ```https://domain.tld/yunohost/api/users``` + correspond à une requete `GET /users` vers l'API YunoHost. Cette requête + est mappée sur `user_list()`. Accéder à cette URL devrait afficher le json + retourné par cette fonction. Les requêtes `GET' sont typiquement destinées à + demander de l'information au serveur, tandis que les requêtes `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éfinit 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` contient 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 rafraîchissement 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 vos 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 10b76cd5..5e08e9b3 100644 --- a/sitemap.md +++ b/sitemap.md @@ -81,16 +81,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 4693043f..550b1e97 100644 --- a/sitemap_fr.md +++ b/sitemap_fr.md @@ -91,7 +91,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) @@ -104,6 +104,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 cœur 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.