From 9616c2df54bf518e39f2caca79f0db8f3b5f1414 Mon Sep 17 00:00:00 2001 From: Kimonas Sotirchos Date: Wed, 19 Oct 2022 19:22:59 +0300 Subject: [PATCH] proposal: Guidelines for /contrib components (#2286) * proposal: Guidelines for /contrib components Create an initial proposal regarding the expectations we should have around the components in /contrib as well as a deprecation plan for unmaintained components. Signed-off-by: Kimonas Sotirchos * review: Document that components should be working with current KF Signed-off-by: Kimonas Sotirchos * review: Expect link to component's documentation Signed-off-by: Kimonas Sotirchos * review: Expect an UPGRADE.md file as well Signed-off-by: Kimonas Sotirchos * review: Fix typos Signed-off-by: Kimonas Sotirchos * review: Add some testing requirements Signed-off-by: Kimonas Sotirchos Signed-off-by: Kimonas Sotirchos --- .../20220926-contrib-component-guidelines.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 proposals/20220926-contrib-component-guidelines.md diff --git a/proposals/20220926-contrib-component-guidelines.md b/proposals/20220926-contrib-component-guidelines.md new file mode 100644 index 0000000000..379937e0b4 --- /dev/null +++ b/proposals/20220926-contrib-component-guidelines.md @@ -0,0 +1,65 @@ +# Guidelines for /contrib Components + +**Authors**: Kimonas Sotirchos kimwnasptd@arrikto.com + +The motivation behind this proposal is to fully document expectations and +requirements that components under `/contrib` should satisfy. This will make it +more clear how to use a component, how it integrates with Kubeflow, the problems +it tries to solve as well as dependency versions. + +## Goals + +* Document requirements that components under `/contrib` should satisfy +* Introduce a process for deprecating unmaintained components + +## Non-Goals + +* Get into the discussion of which components are considered "Kubeflow" components + * The assumption until now is that components under the Kubeflow GitHub Org live + under the `/apps` dir, and all others under `/contrib` +* Provide a migration plan for components to move out from `/contrib` +* Modify the [`example/kustomization.yaml`](https://github.com/kubeflow/manifests/blob/master/example/kustomization.yaml) with new components + +## Proposal + +### Component Requirements + +Components living under `/contrib` should satisfy some strict requirements to +ensure they are always usable by end-users and contain complementary documentation. + +These are the requirements for all components under `/contrib`: +1. There must be a `README.md` file that documents: + * Instructions on how someone can install the component in a Kubeflow cluster + * Since Kubeflow manifests have standardized on [Kustomize](https://kustomize.io/) + we expect all manifests to be a kustomize packages + * How to use the component as part of Kubeflow (examples) + * The problems it tries to solve and the value it brings + * Links to the official documentation of the component +2. There must be an OWNERS file with at least 2 users +3. The component must work with the latest version of Kubeflow, and its + dependencies +4. There must be an `UPGRADE.md` file that documents any instructions users need + to follow when applying manifests of a newer version +5. There needs to be sufficient work on testing + * There must be a script file [python, bash etc] that vefiries the component + is working as expected. This can be something very simple, like submitting a + CustomResource and waiting for it to become Ready + * The maintainers will need to work with the leads of Manifests WG to ensure + there's some basic automation in place that will be running the above script(s) + +At this point we don't want to provide too much of a strict structure for the +README. Developers are free to expose any other information in the README that +they find fit, as long as the above info is exposed. + + +### Deprecation plan + +The proposed criteria for deciding that a component should be deprecated are: +1. The component can not be installed in the minimum K8s version supported by Kubeflow +2. The manifests are not working as expected and result in undeployable Pods +3. The documented examples do not work as expected + +If a component meets all the above criteria then it will initially be marked as +UNMAINTAINED/OUT-OF-DATE, in the component's README. Then if a whole Kubeflow release +cycle concludes and the component is still in UNMAINTAINED/OUT-OF-DATE phase and +without any feedback from the OWNERS, it will be removed.