From e973f723bd272283e031411f2d24b6ecb4bf5dd8 Mon Sep 17 00:00:00 2001 From: decentral1se Date: Thu, 30 Sep 2021 15:15:44 +0200 Subject: [PATCH] docs: new versioning scheme incoming --- ...er-guide.md => recipe-maintainer-guide.md} | 107 +++--------------- mkdocs.yml | 2 +- 2 files changed, 16 insertions(+), 93 deletions(-) rename docs/{packager-guide.md => recipe-maintainer-guide.md} (54%) diff --git a/docs/packager-guide.md b/docs/recipe-maintainer-guide.md similarity index 54% rename from docs/packager-guide.md rename to docs/recipe-maintainer-guide.md index 084b8f4..f37523a 100644 --- a/docs/packager-guide.md +++ b/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 -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. +> We are still working on stabilising this workflow -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 -which only publish a `latest` or `master` tag, for instance. +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`. -### 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, -we add/increment the `_` part at the end of the version. +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. -So, if you are still on `1.13.4` for Gitea, but you have `mariadb:10.6` upgraded -from `mariadb:10.5`, then the Gitea recipe package version would be `1.13.4_1`. +The commands uses for dealing with this logic in `abra` are: -If you run `abra recipe gitea versions`, you'll see that there are a few -available versions of the `gitea` recipe, two with the same version of the -`gitea` image: +- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe +- `abra recipe tag`: publish a git tag for the recipe repo +- `abra recipe sync`: upgrade the deploy labels to match the new recipe version -``` -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 +## 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)) diff --git a/mkdocs.yml b/mkdocs.yml index 561daf4..1c9152f 100644 --- a/mkdocs.yml +++ b/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