diff --git a/docs/maintainers/index.md b/docs/maintainers/index.md index 484d0696f..7f0b68aed 100644 --- a/docs/maintainers/index.md +++ b/docs/maintainers/index.md @@ -2,16 +2,28 @@ title: Maintainers --- -Welcome to the maintainers guide! Maintainers are typically individuals who have a stake in building up and maintaining our digital configuration commons, the recipe configurations. Maintainers help keep recipes configurations up to date, respond to issues in a timely manner, help new users within the community and recruit new maintainers when possible. +Welcome to the recipe maintainers guide! Recipe maintainers help build up and maintain our recipe configuration commons based on [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/).
-- __New Maintainers Tutorial__ +- __How to Become a Recipe Maintainer™__ - If you want to package a recipe and/or become a maintainer, start here :rocket: + If you want to become a recipe maintainer, start here :heart: + + [Learn more](/maintainers/maintain){ .md-button .md-button--primary } + +- __Package your First Recipe Tutorial__ + + If you want to package a recipe, start here :rocket: [Get Started](/maintainers/tutorial){ .md-button .md-button--primary } +- __How to Upgrade a Recipe__ + + If you want to upgrade a recipe, start here 🤸‍♀️ + + [Start upgrading](/maintainers/upgrade){ .md-button .md-button--primary } + - __Packaging Handbook__ One-stop shop for all you need to know to package recipes :package: diff --git a/docs/maintainers/maintain.md b/docs/maintainers/maintain.md new file mode 100644 index 000000000..f8f29ee81 --- /dev/null +++ b/docs/maintainers/maintain.md @@ -0,0 +1,86 @@ +--- +title: How to Become a Recipe Maintainer +--- + +!!! warning + + This guide is a work-in-progress following [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/) and the work to to implement this in [`#60`](https://git.coopcloud.tech/coop-cloud/traefik/issues/60) for the [traefik recipe](https://git.coopcloud.tech/coop-cloud/traefik). Please help us update this documentation with new conventions and practices that emerge. + +## What does a recipe maintainer do? + +A recipe maintainer takes care of one or more recipes. This includes reviewing issues and pull requests and applying application upgrades which are published upstream. The general expectations for what a recipe maintainer should carry out are defined in [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/). + +If recipes are maintained by several maintainers, there is a greater chance of stability for all operators who deploy those recipe upgrades for end-users. Please consider becoming a maintainer for recipes which you rely on! + +!!! note "We need More Recipe Maintainers!" + + Since the publishing of [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/) there is a growing consensus that it is critically important that we recruit more recipe maintainers. The recipe configuration commons on its own is not enough. We also need to coordinate our maintenance work to ensure that everyone can benefit from smooth and stable upgrades. + +## You can become a recipe maintainer! + +Anyone who deploys a recipe can become a recipe maintainer. If you want to ensure that a recipe becomes stable and reliable, then you can become the maintainer. If you maintain a recipe alone, ask for help and encourage others to join in. The only way we can reduce the endless workload of application updates is to coordinate our work together. + +You can start by reading The Maintainers Proposal: [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/). Check if there are maintainers mentioned in the `README.md` of the recipe repository and if there is a `MAINTENANCE.md` present. For example, for the traefik recipe, here is [the list of maintainers in the `README.md`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/8eaee04b5d9980a99fdad57677a4c72d7796da10/README.md?display=source#L8) and the maintainers guidelines in the [`MAINTENANCE.md`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/8eaee04b5d9980a99fdad57677a4c72d7796da10/MAINTENANCE.md). + +If there is no `MAINTENANCE.md`, copy the template below and create your own. + +### `MAINTENANCE.md` template + +!!! warning + + We are still considering if it is a good idea to create a `MAINTENANCE.md` + for every recipe repository. Maybe it is a better idea to make a single + `MAINTENANCE.md` on [docs.coopcloud.tech](https://docs.coopcloud.tech). We + look forward to your input. + +``` +# Recipe Maintenance + +All contributions should be made via a pull request. This is to ensure a +certain quality and consistency, that others can rely on. + +## Maintainer Responsibilities + +A recipe maintainer has the following responsibilities: + +- Respond to pull requests / issues within a week +- Make image security updates within a day +- Make image patch / minor updates within a week +- Make image major updates within a month + +In order to fullfill these responsibilities a recipe maintainer: + +- Has to watch the repository (to get notifications) +- Needs to make sure renovate is configured properly + +## Pull Requests + +A pull request can be merged if it is approved by at least one maintainer. For +pull requests opened by a maintainer they need to be approved by another +maintainer. + +## Become a maintainer + +Everyone can apply to be a recipe maintainer. Simply add your self to the list +in the [README.md](./README.md) and open a new pull request with the change. +``` + +### Pull request template + +``` +--- +name: " pull request template" +--- + + + +* [ ] I have deployed and tested my changes +* [ ] I have [updated relevant versions in `abra.sh`](#TODO) +* [ ] I have made my environment variable changes [backwards compatible](#TODO) +* [ ] I have added a [release note entry](#TODO) +``` diff --git a/docs/maintainers/upgrade.md b/docs/maintainers/upgrade.md new file mode 100644 index 000000000..86e7fbc92 --- /dev/null +++ b/docs/maintainers/upgrade.md @@ -0,0 +1,5 @@ +--- +title: How to Become a Recipe Maintainer +--- + +## TODO