How to Become a Recipe Maintainer
Warning
This guide is a work-in-progress following R025 and the work to to implement this in #60 for the traefik recipe. 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.
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!
We need More Recipe Maintainers!
Since the publishing of R025 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.
README.md and MAINTENANCE.md¶
You can start by reading The Maintainers Proposal: R025. 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 and the maintainers guidelines in the MAINTENANCE.md. If there is no MAINTENANCE.md, copy the template below and create your own.
Maintainers Team¶
It is important that only recipe maintainers have write permissions to the repository. As it currently stands, every member of the Co-operators Team has write permissions to all recipe repositories for convenience while we are missing enough maintainers.
To change this, create a new team on git.coopcloud.tech/coop-cloud/teams for your specific recipe, e.g. mycoolrecipe-maintainers. Add yourself and any other maintainers. Remove your recipe repository from the list of repositories for the Co-operators Team so that write permissions are removed.
Repository Permissions¶
Under Branch Protection in the recipe repository settings, create a new rule
for the main / master branch of your repository. Add your maintainer team
to the following list of permissions.
- Allow only maintainers to push directly to the main branch
Allowlist Restricted Push>Allowlisted teams for pushing
- Allow only maintainers to approve pull requests
Restrict approvals to allowlisted users or teams>Allowlisted teams for reviews
- Allow only maintainers to merge pull requests
Enable Merge Allowlist>Allowlisted teams for merging
Templates¶
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. We
look forward to seeing feedback on this from new maintainers.
See the MAINTENANCE.md of the Traefik recipe.
Pull request template¶
See the .gitea/PULL_REQUEST_TEMPLATE.md of the Traefik recipe.