Update instructions to update Ansible roles

Also: move the detailed explanation about "just roles" from installing.md to maintenance-upgrading-services.md

TBD: create a dedicated documentation for the "just" program and the concept of its "recipe" (shortcut of commands)

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

docs/installing.md

@@ -8,11 +8,10 @@ If you've configured your DNS records and the playbook, you can start the instal
 
 Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.
 
-To update them, run `just roles` (or `make roles` if you have `make` program on your computer instead of `just`).
+To update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file), run:
 
-`just roles` is a shortcut (a `roles` target defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately runs [agru](https://github.com/etkecc/agru) or [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) (depending on what is available in your system) to download Ansible roles. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`.
-
-**Note**: there's another shortcut (`just update`) which updates the playbook (`git pull`) and updates roles (`just roles`) at the same time.
+- either: `just update`
+- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
 
 If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
 

docs/maintenance-upgrading-services.md

@@ -14,14 +14,18 @@ If you want to be notified when new versions of Synapse are released, you should
 
 ## Steps to upgrade the Matrix services
 
-To upgrade the services:
+Before updating the playbook and the Ansible roles in the playbook, take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of.
+
+If it looks good to you, go to the `matrix-docker-ansible-deploy` directory, then:
 
 - update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using:
 
   - either: `just update`
-  - or: a combination of `git pull` and `just roles` (or `make roles`)
+  - or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
+
+  `just update` and `just roles` are shortcuts (their targets are defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately run [agru](https://github.com/etkecc/agru) or [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) (depending on what is available in your system) to download Ansible roles, after upgrading the playbook (in case of `just update`).
 
-- take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of
+  If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
 
 - re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services:
 
@@ -31,6 +35,6 @@ To upgrade the services:
 
 Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [this page on the playbook tags](playbook-tags.md) for more information.
 
-A way to invoke these `ansible-playbook` commands with less typing is to use [just](https://github.com/casey/just) to run the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information.
+A way to invoke these `ansible-playbook` commands with less typing is to use [just](https://github.com/casey/just) to run the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information. If you don't have `just`, you can also manually run the commands seen in the `justfile`.
 
 **Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).

docs/quick-start.md

@@ -102,7 +102,10 @@ After editing `vars.yml` and `hosts` files, let's start the **installation** pro
 
 Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.
 
-To update them, run `just roles` (or `make roles` if you have `make` program on your computer instead of `just`).
+To update your playbook directory and all upstream Ansible roles, run:
+
+- either: `just update`
+- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
 
 If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`