YunoHost/doc
1
0
Fork 0
mirror of https://github.com/YunoHost/doc.git synced 2024-09-03 20:06:26 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #1353 from ericgaspar/patch-6

Browse source 
Update dev.md
This commit is contained in:
Alexandre Aubin 2020-07-18 00:31:22 +02:00 • committed by GitHub
commit f1a4e0c1af
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 28 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
dev.md
View file

@ -5,9 +5,9 @@ proceed? This guide takes you through the various steps of the development and
contribution process. contribution process.
If you're looking for stuff to implement or fix, the bug-tracker is 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 ### 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. 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 : will want to:
- **Python/CLI core** : work in `/ynh-dev/yunohost/` - **Python/CLI core**: work in `/ynh-dev/yunohost/`
- **Web administration interface** : work in `/ynh-dev/yunohost-admin/` - **Web administration interface**: work in `/ynh-dev/yunohost-admin/`
- You can also work on the other projects on which YunoHost is built - 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 ### 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/). 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: 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 - [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) - [internationalized strings](https://github.com/YunoHost/yunohost/tree/stretch-unstable/locales)
- [tests](https://github.com/YunoHost/yunohost/tree/stretch-unstable/src/yunohost/tests) - [tests](https://github.com/YunoHost/yunohost/tree/stretch-unstable/src/yunohost/tests)
#### SSOwat #### SSOwat
This is the single sign-on system of YunoHost. It both contains: 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 - 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. 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 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: It essentially contains:
- [view templates](https://github.com/YunoHost/yunohost-admin/tree/stretch-unstable/src/views) - [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) - and [internationalized strings](https://github.com/YunoHost/yunohost-admin/tree/stretch-unstable/src/locales)
### Working on the YunoHost Python/CLI core ### 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 category is `domain`, the action is `add`, and `some.domain.tld` is an
argument. 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 functions (and their arguments) located in `src/yunohost/`. For example, typing
`yunohost domain add some.domain.tld` will call the function `yunohost domain add some.domain.tld` will call the function
`domain_add(domainName)` in `domain.py`, with the argument `domainName` equal `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 - The web interface uses the API to interact with YunoHost. The API
commands/requests are also defined via the actionsmap. For instance, accessing 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 /users` requests on the YunoHost API. It is mapped to the function
`user_list()`. Accessing the URL should display the json returned by this `user_list()`. Accessing the URL should display the json returned by this
function. 'GET' requests are typically meant to ask information to the server. function. 'GET' requests are typically meant to ask information to the server.
@ -120,37 +120,37 @@ It essentially contains:
templates. templates.
- `views` contains the various templates for the pages of the interface. In the - `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. `{{some-variable}}`, which will be replaced when building/accessing the page.
It is also possible to have conditions using the It is also possible to have conditions using the
[handlebars.js](http://handlebarsjs.com) syntax : ```{{#if [handlebars.js](http://handlebarsjs.com) syntax: `{{#if
some-variable}}<p>Some conditional HTML code here !</p>{{/if}}``` some-variable}}<p>Some conditional HTML code here !</p>{{/if}}`
- For internationalized strings, use `y18n.t('some-string-code')` in the - 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, 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 ##### Don't forget
- Each time you edit the actionsmap or the python code, you should restart the yunohost-api : - Each time you edit the actionsmap or the Python code, you should restart the YunoHost api:
```systemctl restart yunohost-api``` `systemctl restart yunohost-api`
(You'll need to retype your admin password in the web interface) (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 - 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 ### 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 - Fork the relevant repo on GitHub, and commit stuff to a new branch. We recommend
to name the branch with the following convention : to name the branch with the following convention:
- For an enhancement or new feature : `enh-ISSUENUMBER-name-of-feature` - For an enhancement or new feature: `enh-ISSUENUMBER-name-of-feature`
- For a bugfix `fix-ISSUENUMBER-description-of-fix` - For a bugfix `fix-ISSUENUMBER-description-of-fix`
- `ISSUENUMBER` is optional and is the id of a corresponding ticket on the bug tracker. - `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. `[enh]` at the beginning of the title of your PR.
- After reviewing, testing and validation by other contributors, your branch - After reviewing, testing and validation by other contributors, your branch
should be merged in `unstable` ! should be merged in `unstable`!