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

Apply suggestions from code review

Browse source 
Co-authored-by: Éric Gaspar <46165813+ericgaspar@users.noreply.github.com>
This commit is contained in:
Alexandre Aubin 2022-11-03 12:48:50 +01:00 • committed by GitHub
parent 7b96759add
commit 2679798516
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 10 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
pages/06.contribute/10.packaging_apps/14.advanced/03.packaging_v2/packaging_v2.md
View file

@ -17,8 +17,8 @@ Packaging v2 is a major improvement for the packaging introduced in YunoHost 11.
The motivations for this new format is:
- to get rid of some boring or unecessarily complex or duplicateds stuff such as saving/loading settings, creating a system user, etc.. during the install/upgrade/restore script, which are common things accross many apps.
- to get rid of funky historical, not-super-semantic stuff such as `__FINALPATH__` being replaced by `$final_path` (with underscore), or `__PATH__` being replaced by `$path_url`, etc...
- formalize some aspects such as the existence of the install dir, data dir, apt dependencies, database, etc ... which in turn unlock possible future developments such as computing the space used by an app at one given moment, auto-upgrading apt dependencies during Debian major migration, etc...
- to get rid of funky historical, not-super-semantic stuff such as `__FINALPATH__` being replaced by `$final_path` (with underscore), or `__PATH__` being replaced by `$path_url`, etc.
- formalize some aspects such as the existence of the install dir, data dir, apt dependencies, database, etc. which in turn unlock possible future developments such as computing the space used by an app at one given moment, auto-upgrading apt dependencies during Debian major migration, etc.
- formalize some meta-info such as LDAP/SSO support, architectures supports, and other pre-install / post-install, pre-upgrade / post-upgrade notifications (replacing the infamous `ynh_send_readme_to_admin`) for better UI/UX during the install and upgrade process.
However, this "v2" is not the end of the story and should be seen as an intermediate stage before a "v3" packaging. In particular this "v3" packaging should also formalize the handling of the system and app configurations files and ultimately rework the entire paradigm of the install/remove/upgrade/backup/restore scripts.
@ -39,7 +39,7 @@ This will edit the file in place and you should then carefully review and iterat
- **The manifest is now written as toml (`manifest.toml`)** instead of json (`manifest.json`). The structure of the manifest itself has been reworked and now include:
- The `upstream` section (now mandatory)
- An `integration` section meant to formalize what minimum yunohost version is required, the list of supported architectures, declare if SSO/LDAP is supported, typical resource usage. This is meant to be displayed both in the catalog (similar to app stores) and on the app info page after installing the app - though this is still work in progress.
- An `integration` section meant to formalize what minimum YunoHost version is required, the list of supported architectures, declare if SSO/LDAP is supported, typical resource usage. This is meant to be displayed both in the catalog (similar to app stores) and on the app info page after installing the app - though this is still work in progress.
- A `resource` section (detailed below)
- **Install questions are now automatically saved as settings** (except user-provided password and other specific infos)
- **All settings are now automatically loaded in app script environments** (so e.g. directly define `$domain`, etc.)
@ -48,19 +48,19 @@ This will edit the file in place and you should then carefully review and iterat
- **Introduce a new `resource` mechanism**
- Resources are declared in the `manifest.toml`.
- They are meant to formalize recurring app needs that are to be provisioned/deprovisioned by the core.
- They include for example : system user, apt dependencies, install dir, data dir, port, permissions, SQL database ...
- They include for example: system user, apt dependencies, install dir, data dir, port, permissions, SQL database...
- Each resource is to be provisioned *before* running the install script, deprovisioned *after* the remove script, and automatically upgraded if needed before running the upgrade script (or provisionned if introduced in the new app version, or deprovisioned if removed w.r.t. the previous app version)
- More infos about resources and their options and behavior are available in the dedicated doc page
- **Permissions are automatically initialized using the answer to the `init_main_permission` install question** (replacing the `is_public` question). No need to write a boring `if $is_public ...` in the install script to add visitors anymore ! There is a similar mechanism to init other permissions, eg `init_admin_permission` (cf also the doc about the `permission` resource)
- **The content of the `doc/` folder is now meant to be integrated in the webadmin** (though this is still WIP as of writing this). In particular:
- `DESCRIPTION.md` and the `screenshots/` folder are expected to be displayed prior to the app install form (similar to app stores on mobile)
- `ADMIN.md` is expected to be made available somewhere in the info page and should contain technical admin notes. Other pages can be defined (just name it `WHATEVER.md`). Lang codes are also supported following the existing scheme for the README, eg `README_fr.md` is the french version, hence you can create `ADMIN_fr.md`, etc.
- `ADMIN.md` is expected to be made available somewhere in the info page and should contain technical admin notes. Other pages can be defined (just name it `WHATEVER.md`). Lang codes are also supported following the existing scheme for the README, eg `README_fr.md` is the French version, hence you can create `ADMIN_fr.md`, etc.
- **The content of the `doc/notification/` folder is meant to replace the `ynh_send_readme_to_admin` mechanics**. The integration of these in the webadmin is still work in progress. You can create:
- `doc/notifications/pre_install.md` : a note to be displayed prior to the app install. Typically to warn of something unusual, such as "the app install will automatically add 1GB swap to the system".
- `doc/notifications/post_install.md` : a note to be displayed after the app install. Typically to explain post-install operations to be performed manually by the admin and that cannot be automated.
- `doc/notifications/pre_upgrade.md` : a note to be displayed prior to any upgrade of this app.
- `doc/notifications/pre_upgrade.d/{version}.md` : a note to be displayed prior to a specific version upgrade.
- `doc/notifications/post_upgrade.md` : a note to be displayed after the app upgrade. For example in the context of Nextcloud, the fact that you may need to re-enable custom modules manually ?
- `doc/notifications/pre_install.md`: a note to be displayed prior to the app install. Typically to warn of something unusual, such as "the app install will automatically add 1GB swap to the system".
- `doc/notifications/post_install.md`: a note to be displayed after the app install. Typically to explain post-install operations to be performed manually by the admin and that cannot be automated.
- `doc/notifications/pre_upgrade.md`: a note to be displayed prior to any upgrade of this app.
- `doc/notifications/pre_upgrade.d/{version}.md`: a note to be displayed prior to a specific version upgrade.
- `doc/notifications/post_upgrade.md`: a note to be displayed after the app upgrade. For example in the context of Nextcloud, the fact that you may need to re-enable custom modules manually?
- **Replace some historical names with more sensible ones**, or homogenize some practices:
- `final_path` is now `install_dir` (this migration should be automatically handled by the core and the `convert_app_to_packaging_v2.py` script)
- `datadir` is now `data_dir` to be consistent with `install_dir` (this migration should be automatically handled by the core and the `convert_app_to_packaging_v2.py` script)