diff --git a/dev.md b/dev.md index 45015d78..6dcf0977 100644 --- a/dev.md +++ b/dev.md @@ -5,9 +5,9 @@ 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://github.com/YunoHost/issues/issues) ! +[here](https://github.com/YunoHost/issues/issues)! -**Come say hi to us in the [dev chatroom](/chat_rooms)** ! +**Come say hi to us in the [dev chat room](/chat_rooms)**! ### Setting up a development environment @@ -18,11 +18,11 @@ If you're looking for stuff to implement or fix, the bug-tracker is 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 `/ynh-dev/yunohost/` - - **Web administration interface** : work in `/ynh-dev/yunohost-admin/` + will want to: + - **Python/CLI core**: work in `/ynh-dev/yunohost/` + - **Web administration interface**: work in `/ynh-dev/yunohost-admin/` - You can also work on the other projects on which YunoHost is built - (SSOwat, moulinette) in similar ways + (SSOwat, Moulinette) in similar ways ### Overview of the 4 main pieces of YunoHost @@ -38,30 +38,30 @@ small technical utilitary functions (e.g. reading/writing json). Moulinette has its own documentation available [here](https://moulinette.readthedocs.io/en/latest/). -#### Yunohost +#### YunoHost This piece is the very core of YunoHost. It contains: -- [the python code](https://github.com/YunoHost/yunohost/tree/stretch-unstable/src/yunohost) that manages users, domains, apps, services and other things +- [the Python code](https://github.com/YunoHost/yunohost/tree/stretch-unstable/src/yunohost) that manages users, domains, apps, services and other things - [bash helpers](https://github.com/YunoHost/yunohost/tree/stretch-unstable/data/helpers.d) mainly used by application packagers to package applications -- [hooks](https://github.com/YunoHost/yunohost/tree/stretch-unstable/data/hooks) and [templates](https://github.com/YunoHost/yunohost/tree/stretch-unstable/data/templates) that are used to configure the various pieces of the ecosystem such as nginx, postfix, ... +- [hooks](https://github.com/YunoHost/yunohost/tree/stretch-unstable/data/hooks) and [templates](https://github.com/YunoHost/yunohost/tree/stretch-unstable/data/templates) that are used to configure the various pieces of the ecosystem such as NGINX, Postfix... - [internationalized strings](https://github.com/YunoHost/yunohost/tree/stretch-unstable/locales) - [tests](https://github.com/YunoHost/yunohost/tree/stretch-unstable/src/yunohost/tests) #### SSOwat This is the single sign-on system of YunoHost. It both contains: -- [Lua scripts](https://github.com/YunoHost/ssowat) that are directly interfaced with nginx and handle all the "technical" aspects of authentication and route accesses +- [Lua scripts](https://github.com/YunoHost/ssowat) that are directly interfaced with NGINX and handle all the "technical" aspects of authentication and route accesses - the web [user portal](https://github.com/YunoHost/SSOwat/tree/stretch-unstable/portal) which is the interface used by YunoHost's end users to log in and browse installed apps SSOwat is configured through `/etc/ssowat/conf.json` which is generated by YunoHost. -#### Yunohost-admin +#### YunoHost-admin It is an *optional* dependency of YunoHost and corresponds to an interface for the web API created by YunoHost and Moulinette (c.f. the `yunohost-api` service). It essentially contains: - [view templates](https://github.com/YunoHost/yunohost-admin/tree/stretch-unstable/src/views) -- corresponding [javascript controllers](https://github.com/YunoHost/yunohost-admin/tree/stretch-unstable/src/js/yunohost/controllers) that interact with the Yunohost API +- corresponding [javascript controllers](https://github.com/YunoHost/yunohost-admin/tree/stretch-unstable/src/js/yunohost/controllers) that interact with the YunoHost API - and [internationalized strings](https://github.com/YunoHost/yunohost-admin/tree/stretch-unstable/src/locales) ### Working on the YunoHost Python/CLI core @@ -77,7 +77,7 @@ It essentially contains: category is `domain`, the action is `add`, and `some.domain.tld` is an argument. -- Moulinette will automatically map commands in the actionsmap to python +- 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 @@ -107,7 +107,7 @@ It essentially contains: - 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 + 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. @@ -120,37 +120,37 @@ It essentially contains: 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 + 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}}``` + [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 + 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/) ! + this will be done using [Weblate](https://translate.yunohost.org/)! ##### Don't forget -- Each time you edit the actionsmap or the python code, you should restart the yunohost-api : - ```systemctl restart yunohost-api``` - (You'll need to retype your admin password in the web interface) +- Each time you edit the actionsmap or the Python code, you should restart the YunoHost api: + `systemctl restart yunohost-api` + (You'll need to retype your admin and 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`). + 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-ISSUENUMBER-name-of-feature` +- 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-ISSUENUMBER-name-of-feature` - For a bugfix `fix-ISSUENUMBER-description-of-fix` - `ISSUENUMBER` is optional and is the id of a corresponding ticket on the bug tracker. -- Once you're ready, open a Pull Request (PR) on Github. Please include `[fix]` or +- 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 `unstable` ! +should be merged in `unstable`!