docs: new versioning scheme incoming

docs/recipe-maintainer-guide.md

@@ -1,8 +1,8 @@
 ---
-title: Packager guide
+title: Recipe maintainer guide
 ---
 
-## Package your first application
+## Package your first recipe
 
 Let's take as an example, [Matomo web analytics](https://matomo.org/).
 
@@ -55,7 +55,7 @@ abra app new matomo --secrets \
  --domain matomo.swarm.example.com \
  --server swarm.example.com \
  --app-name mygreatapp
- ```
+```
 
 Depending on whether you defined any extra environment variables -- we didn't so
 far, in this example -- you might want to run `abra app mygreatapp config` to
@@ -69,103 +69,26 @@ abra app mygreatapp deploy
 
 Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables -- if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
 
-## How apps are versioned
+## How recipes are versioned
 
-Co-op Cloud follows the version scheme of the applications we're packaging, as
+> We are still working on stabilising this workflow
-far as possible; for example, [version `1.13.4` of our Gitea recipe][gitea]
-contains version `1.13.4` of Gitea. We're trying not to invent a new versioning
-scheme.
 
-This approach is still work-in-progress.
+We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).
 
-Versions are based on [Docker image tags][tags]: we don't currently have a plan for apps
+The Gitea project maintains a version, e.g. `1.14.3`. This version uses the [semver](https://semver.org) strategy for communicating what type of changes are included in each version, i.e., if there is a breaking change, Gitea will release a new version as `2.0.0`.
-which only publish a `latest` or `master` tag, for instance.
 
-### Versioning different services
+However, there are other types of changes that can happen for a recipe. Perhaps the database image gets a breaking update or the actual recipe configuration changes some environment variable. This can mean that end-users of the recipe need to do some work to make sure their updates will deploy successfully.
 
-Most apps have underlying services like databases and/or caches.
+Therefore, we maintain an additional version part, in front of the project version. So, the first release of the Gitea recipe in the Co-op Cloud project has the version of `1.0.0+1.14.3-rootless`. This `x.y.z+` is the version part that the recipe maintainer manages. If a new available Gitea version comes out as `1.15-rootless` then the recipe maintainer will publish `1.1.0+1.15-rootless` as this is a backwards compatible update, following semantic versioning.
 
-When there's a new version of one of these services, but not the "main" service,
+In all cases, we follow the semver semantics. So, if we upgrade the Gitea recipe from `1.14.3-rootless` to `1.15.3-rootless`, we still publish `1.1.0+1.15.3-rootless` as our recipe version. In this case, we skipped a few patch releases but it was all backwards compatible, so we only increment the minor version part.
-we add/increment the `_<revision>` part at the end of the version.
 
-So, if you are still on `1.13.4` for Gitea, but you have `mariadb:10.6` upgraded
+The commands uses for dealing with this logic in `abra` are:
-from `mariadb:10.5`, then the Gitea recipe package version would be `1.13.4_1`.
 
-If you run `abra recipe gitea versions`, you'll see that there are a few
+- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe
-available versions of the `gitea` recipe, two with the same version of the
+- `abra recipe tag`: publish a git tag for the recipe repo
-`gitea` image:
+- `abra recipe sync`: upgrade the deploy labels to match the new recipe version
 
-```
+## Style guide
-1.14.1-rootless:
- - app (gitea/gitea:1.14.1-rootless, 6244e9fc)
- - db (mariadb:10.5, 36288c67)
-1.14.1-rootless_1:
- - app (gitea/gitea:1.14.1-rootless, 6244e9fc)
- - db (mariadb:10.6, 718cb856)
-1.14.2-rootless:
- - app (gitea/gitea:1.14.2-rootless, bedf8d12)
- - db (mariadb:10.6, 718cb856)
-```
-
-Versions `1.14.1-rootless` and `1.14.1-rooless_1` differ only in their version
-of the `mariadb` service. If there had been several updates to the `mariadb`
-image in between updates to the `gitea` image, there might have also been
-`1.14.1-rooless_2`, `1.14.1-rooless_3` -- this is more likely with recipes which
-include services with several different images.
-
-!!! note
-
-    Not all of these updates will be released as installable Co-op Cloud recipes
-    -- in this example, there's no version with `gitea:1.14.2-rootless` and
-    `mariadb:10.5`. If you need a specific combination, create a pull request or
-    issue in the repository for the app recipe!
-
-[gitea]: https://git.autonomic.zone/coop-cloud/gitea/src/tag/1.13.4
-[tags]: https://docs.docker.com/engine/reference/commandline/tag/
-
-## Automation
-
-### Upgrades
-
-See [autonomic-cooperative/renovate-bot](https://git.autonomic.zone/autonomic-cooperative/renovate-bot).
-
-### Releases
-
-```
----
-kind: pipeline
-name: recipe release
-steps:
-  - name: release a new version
-    image: thecoopcloud/drone-abra:latest
-    settings:
-      command: recipe YOURRECIPE release
-      deploy_key:
-        from_secret: abra_bot_deploy_key
-```
-
-### Failure notifications
-
-```yaml
-  - name: notify coopcloud-dev on failure
-    image: plugins/matrix
-    settings:
-      homeserver: https://matrix.autonomic.zone
-      roomid: "IFazIpLtxiScqbHqoa:autonomic.zone"
-      userid: "@autono-bot:autonomic.zone"
-      accesstoken:
-        from_secret: autono_bot_access_token
-    depends_on:
-    - deployment
-  when:
-    status:
-      - failure
-```
-
-### Github mirroring
-
-See [auto-mirror](https://git.autonomic.zone/coop-cloud/auto-mirror).
-
-## Packaging style guide
 
 - Please don't use `&image` YAML repeat anchors on the `image: ...` key because our `recipe release` logic does not handle it (see [#172](https://git.autonomic.zone/coop-cloud/abra/issues/172))

mkdocs.yml

@@ -39,7 +39,7 @@ nav:
       - Deploy your first app: deploy.md
   - App catalogue: apps.md
   - App config guide: app-config-guide.md
-  - Packager guide: packager-guide.md
+  - Recipe maintainer guide: recipe-maintainer-guide.md
   - Frequently asked questions: faq.md
   - Contributing guide: contribute.md
   - Community organising: comm-org.md