add contributing guidelines

Signed-off-by: Sebastian Hoß <[email protected]>

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+<!--
+SPDX-FileCopyrightText: The kube-custom-resources-rs Authors
+SPDX-License-Identifier: 0BSD
+ -->
+
+# Contributor Guide
+
+:+1::tada: Thanks a lot for taking your time to contribute! :tada::+1:
+
+## Adding new CRDs
+
+To add new custom resource definitions to this project, please follow the steps outlined below. If anything is unclear or does not work on your computer, please don't hesitate to reach out or just create a partial pull request on GitHub with your current progress.
+
+### 0. Required Software
+
+In order to run all the commands mentioned below, you will need the following installed on your computer:
+
+- `rust`/`cargo`: https://www.rust-lang.org/tools/install
+- `kopium`: https://github.com/kube-rs/kopium
+- `yq`: https://github.com/mikefarah/yq
+- `bash`: https://www.gnu.org/software/bash/
+
+### 1. Add CRD to catalog
+
+All CRDs of this project are managed in the [catalog](https://github.com/metio/kube-custom-resources-rs/blob/main/code-generator/src/catalog.rs) which contains a long list of projects along with the CRDs they are producing. We try to sort this list alphabetically in order to make it easier finding things, but this is not a hard requirement for your contribution. Each entry requires the following details:
+
+- `project_name`: The organization and name of a project, e.g. `prometheus-operator/prometheus-operator` is used for the project at https://github.com/prometheus-operator/prometheus-operator.
+- `license`: The SPDX license identifier for the CRD files. This is usually the same license as the project and the catalog file already contains constants for the most common licenses.
+- `urls`: The list of URLs where CRDs are located. It does not matter if that file contains other Kubernetes resources, our tooling will only extract CRDs from those files.
+
+### 2. Fetch the CRD
+
+We save a copy of all CRDs as part of this repository. In order to fetch your newly added CRDs run:
+
+```console
+$ cargo run --package code-generator --bin crd_v1_fetcher <project_name>
+```
+
+The `<project_name>` argument is the same value you added to the catalog in step 1, e.g.:
+
+```console
+$ cargo run --package code-generator --bin crd_v1_fetcher prometheus-operator/prometheus-operator
+```
+
+Note: You can run that binary without any argument in which case it will download **all** CRDs in the catalog.
+
+### 3. Update the dep5 file
+
+We want to be a [reuse](https://reuse.software/) compliant project and therefore need to attribute each file with its proper license. The [dep5](./.reuse/dep5) file contains license information for all CRDs. It is automatically generated by calling the following command and uses the license information you added to the catalog in step 1:
+
+```console
+$ cargo run --package code-generator --bin dep5_generator
+```
+
+### 4. Generate Custom Resources
+
+Once we have all CRDs, we can generate Rust code for the custom resources with [kopium](https://github.com/kube-rs/kopium) by calling the following bash script from the root of this project:
+
+```console
+$ ./code-generator/generate.sh <project_name>
+```
+
+The `<project_name>` argument is again the same value you added to the catalog in step 1, e.g.:
+
+```console
+$ ./code-generator/generate.sh prometheus-operator/prometheus-operator
+```
+
+Note: You can run that script without any argument in which case it will generate code for **all** CRDs in the catalog.
+
+### 5. Update lib.rs
+
+Each group/version of every Kubernetes kind has its own feature in this project. All of them are referenced in the [lib.rs](./kube-custom-resources-rs/src/lib.rs) file which is automatically generated by calling:
+
+```console
+$ cargo run --package code-generator --bin lib_rs_generator
+```

code-generator/generate.sh

@@ -3,9 +3,15 @@
 # SPDX-FileCopyrightText: The kube-custom-resources-rs Authors
 # SPDX-License-Identifier: 0BSD
 
+FILTER="${1:-}"
 
 ### Generate code with kopium
 for file in $(find ./crd-catalog -name '*.yaml' -type f | LC_ALL=C sort --general-numeric-sort); do
+  if [ -n "${FILTER}" ]; then
+    if ! echo -n "${file}" | grep --quiet "${FILTER}"; then
+      continue
+    fi
+  fi
   crd=$(basename "${file%.*}")
   version=$(basename "$(dirname "${file}")")
   group=$(basename "$(dirname "$(dirname "${file}")")")
@@ -239,14 +245,31 @@ BUGGY_RESOURCES=(
   work_karmada_io_v1alpha1/works
 )
 for resource in "${BUGGY_RESOURCES[@]}"; do
-  echo "removing ${resource}"
   rm --force "./kube-custom-resources-rs/src/${resource}.rs"
 done
 
 
 ### Generate mod.rs files
-find ./kube-custom-resources-rs/src -name mod.rs -type f -delete
 for file in $(find ./crd-catalog -name '*.yaml' -type f | LC_ALL=C sort --general-numeric-sort); do
+  if [ -n "${FILTER}" ]; then
+    if ! echo -n "${file}" | grep --quiet "${FILTER}"; then
+      continue
+    fi
+  fi
+  crd=$(basename "${file%.*}")
+  version=$(basename "$(dirname "${file}")")
+  group=$(basename "$(dirname "$(dirname "${file}")")")
+  rust_group=$(echo "${group}" | sed -e 's/\./_/g' -e 's/-/_/g')
+  module="${rust_group}_${version}"
+
+  rm --force "./kube-custom-resources-rs/src/${module}/mod.rs"
+done
+for file in $(find ./crd-catalog -name '*.yaml' -type f | LC_ALL=C sort --general-numeric-sort); do
+  if [ -n "${FILTER}" ]; then
+    if ! echo -n "${file}" | grep --quiet "${FILTER}"; then
+      continue
+    fi
+  fi
   crd=$(basename "${file%.*}")
   version=$(basename "$(dirname "${file}")")
   group=$(basename "$(dirname "$(dirname "${file}")")")
@@ -255,7 +278,7 @@ for file in $(find ./crd-catalog -name '*.yaml' -type f | LC_ALL=C sort --genera
   module="${rust_group}_${version}"
 
   if [ -f "./kube-custom-resources-rs/src/${module}/${rust_crd}.rs" ]; then
-    echo "pub mod ${rust_crd};" >>"./kube-custom-resources-rs/src/${module}/mod.rs"
+    echo "pub mod ${rust_crd};" >> "./kube-custom-resources-rs/src/${module}/mod.rs"
   fi
 done