From 4d67caff565ea750a5447519cf0a8bc023be3176 Mon Sep 17 00:00:00 2001 From: kawaiipunk Date: Wed, 2 Jul 2025 12:56:16 +0100 Subject: [PATCH] Improving the catalogue docs --- docs/maintainers/catalogue.md | 65 ++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/docs/maintainers/catalogue.md b/docs/maintainers/catalogue.md index f9e2a4d..0678859 100644 --- a/docs/maintainers/catalogue.md +++ b/docs/maintainers/catalogue.md @@ -8,7 +8,7 @@ title: The Recipe Catalogue > `coop-cloud` "Organisation" on https://git.coopcloud.tech. > > This is a temporary situation, we want to open out this process & also introduce some automation -> to support making thie process more convenient. Please nag us to move things along. +> to support making thie process more convenient. Please nag us to move things along on Matrix. - Publish your new recipe on the [git.coopcloud.tech](https://git.coopcloud.tech/coop-cloud) "Organisation" - Run `abra catalogue generate -p` @@ -26,36 +26,7 @@ For now, it is best to [get in touch](https://docs.coopcloud.tech/intro/contact/ In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139). -## How do I generate the recipe catalogue - -To generate an entire new copy of the catalogue: - -``` -abra catalogue generate -``` - -You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting. - -If you just want to generate a catalogue entry for a single recipe: - -``` -abra catalogue generate -``` - -The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running: - -``` -cd ~/.abra/catalogue -git diff -``` - -You can pass `--publish` to have `abra` automatically publish those changes. - -!!! warning "Here be more SSH dragons" - - In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it. - -## How do I make the catalogue automatically regenerate after new versions are published? +## How do I make the catalogue automatically regenerate after new recipe versions are published? "I'd like to make it so that whenever I push a new git tag to the [`coop-cloud/rallly` repository](https://git.coopcloud.tech/coop-cloud/rallly) @@ -90,3 +61,35 @@ The expectation is that this repo will only be updated automatically. While manu Automatic regeneration is handled by this Drone step, in the separate `auto-recipes-catalogue-json` repo: https://git.coopcloud.tech/toolshed/auto-recipes-catalogue-json/src/branch/main/.drone.yml#L5-L25 This is run on a daily schedule (question: where is `nightly-app-date` configured?), and can also be triggered by recipe repositories to make new versions available quicker – see "[How do I make the catalogue automatically regenerate after new versions are published?](#how-do-i-make-the-catalogue-automatically-regenerate-after-new-versions-are-published)" above. + +## How do I manually generate the recipe catalogue + +> These days, doing this is only useful in the event of troubleshooting the automatic catalogue regeneration + +To generate an entire new copy of the catalogue: + +``` +abra catalogue generate +``` + +You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting. + +If you just want to generate a catalogue entry for a single recipe: + +``` +abra catalogue generate +``` + +The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running: + +``` +cd ~/.abra/catalogue +git diff +``` + +You can pass `--publish` to have `abra` automatically publish those changes. + +!!! warning "Here be more SSH dragons" + + In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it. +