You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,11 @@
2
2
3
3
## Code of Conduct
4
4
5
-
All members of the project community must abide by the [SAP Open Source Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md).
5
+
All members of the project community must abide by the [SAP Open Source Code of Conduct](https://github.com/openmcp-project/.github/blob/main/CODE_OF_CONDUCT.md).
6
6
Only by respecting each other we can develop a productive, collaborative community.
7
-
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting [a project maintainer](.reuse/dep5).
7
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [[email protected]](mailto:[email protected]) (SAP Open Source Program Office). All complaints will be reviewed and investigated promptly and fairly.
8
+
9
+
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
Copy file name to clipboardExpand all lines: README.md
+163-3Lines changed: 163 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,169 @@
6
6
7
7
OpenMCP build and CI scripts
8
8
9
-
## Requirements and Setup
9
+
The Kubernetes operators in the openmcp-project use mostly the same `make` targets and surrounding scripts. This makes sense, because this way developers do not have to think about in which repo they are working right now - `make tidy` will always tidy the go modules.
10
+
The drawback is that all `make` targets and scripts have to be kept in sync. If the `make` targets have the same name but a different behavior (conceptually, not code-wise), this will became more of an disadvantage than an advantage. This 'keeping it in sync' means that adding an improvement to any of the scripts required this improvement to be added to all of the script's copies in the different repositories, which is annoying and error-prone.
10
11
11
-
*Insert a short description what is required to get your project running...*
12
+
To improve this, the scripts that are shared between the different repositories have been moved into this repository, which is intended to be used as a git submodule in the actual operator repositories.
13
+
14
+
Instead of `make`, we have decided to use the [task](https://taskfile.dev/) tool.
15
+
16
+
## Requirements
17
+
18
+
It is strongly recommended to include this submodule under the `hack/common` path in the operator repositories. While most of the coding is designed to work from anywhere within the including repository, there are some workarounds for bugs in `task` which rely on the assumption that this repo is a submodule under `hack/common` in the including repository.
⚠️⚠️⚠️ There is currently a [bug](https://github.com/go-task/task/issues/2108) in the `task` tool which causes it to not propagate variables from the top-level `vars` field to the included Taskfiles properly. As a workaround, the variables have to be specified in `includes.*.vars` instead.
53
+
54
+
> `ROOT_DIR` is a task-internal variable that points to the directory of the root Taskfile.
55
+
56
+
Since the imported Taskfile is generic, there are a few variables that need to be set in order to configure the tasks correctly. Unless specified otherwise, the variables must not be specified if their respective purpose doesn't apply to the importing repository (e.g. `NESTED_MODULES` is not required if there are no nested modules).
57
+
- `NESTED_MODULES`
58
+
- List of nested modules, separated by spaces.
59
+
- Note that the module has to be located in a subfolder that matches its name.
60
+
- Required for multiple tools from the golang environment which are able to work on a single module only and therefore have to be called once per go module.
61
+
- `API_DIRS`
62
+
- List of files with API type definitions for which k8s CRDs should be generated.
63
+
- The `<directory>/...` syntax can be used to refer to all files in the directory and its subdirectories.
64
+
- This is fed into the k8s code generation tool for CRD generation.
65
+
- `MANIFEST_OUT`
66
+
- Directory where the generated CRDs should be put in.
67
+
- `CODE_DIRS`
68
+
- List of files with go code, separated by spaces.
69
+
- The `<directory>/...` syntax can be used to refer to all files in the directory and its subdirectories.
70
+
- Formatting and linting checks are executed on these files.
71
+
- This variable must always be specified.
72
+
- `COMPONENTS`
73
+
- A list of 'components' contained in this repository, separated by spaces.
74
+
- This is relevant for binary, image, chart, and OCM component building. Each entry will result in a separate build artifact for the respective builds.
75
+
- A 'component' specified here has some implications:
76
+
- A `cmd/<component>/main.go` file is expected for binary builds.
77
+
- A separate docker image will be built for each component.
78
+
- If the component has a helm chart, it is expected under `charts/<component>/`.
79
+
- Note that support for helm charts is not fully implemented yet.
80
+
- Each component will get its own OCM component.
81
+
- Note that support for OCM components is not implemented yet.
82
+
- Library repos will not have any component, operator repos will mostly contain just a single component (the operator itself).
83
+
- `REPO_URL`
84
+
- URL of the github repository that contains the Taskfile.
85
+
- This is used for building the OCM component, which will fail if it is not specified.
86
+
- `GENERATE_DOCS_INDEX`
87
+
- If this is set and its value is not `false`, the `generate:docs` target will generate a documentation index at `docs/README.md`. Otherwise, the task is skipped.
88
+
- See below for a short documentation of the the index generation.
89
+
90
+
There are two main Taskfiles, one of which should be included:
91
+
- `Taskfile_controller.yaml`is meant for operator repositories and contains task definitions for code generation and validation, binary builds, and image builds.
92
+
- `Taskfile_library.yaml`is meant for library repos and does not include the tasks for binary and image building.
93
+
94
+
A minimal Taskfile for a library repository could look like this:
95
+
```yaml
96
+
version: 3
97
+
98
+
vars:
99
+
CODE_DIRS: '{{.ROOT_DIR}}/pkg/...'
100
+
101
+
includes:
102
+
shared:
103
+
taskfile: hack/common/Taskfile_library.yaml
104
+
flatten: true
105
+
```
106
+
107
+
#### Overwriting and Excluding Task Definitions
108
+
109
+
Adding new specialized tasks in addition to the imported generic ones is straightforward: simply add the task definitions in the importing Taskfile.
110
+
111
+
It is also possible to exclude or overwrite generic tasks. The following example uses an `external-apis` task that should be executed as part of the generic `generate:code` task.
112
+
113
+
Overwriting basically works by excluding and re-defining the generic task that should be overwritten. If the generic task's logic should be kept as part of the overwritten definition, the generic file needs to be imported a second time with `internal: true`, so that the original task can be called.
114
+
115
+
```yaml
116
+
includes:
117
+
shared:
118
+
taskfile: hack/common/Taskfile_controller.yaml
119
+
flatten: true
120
+
excludes: # put task names in here which are overwritten in this file
121
+
- generate:code
122
+
common: # imported a second time so that overwriting task definitions can call the overwritten task with a 'c:' prefix
123
+
taskfile: hack/common/Taskfile_controller.yaml
124
+
internal: true
125
+
aliases:
126
+
- c
127
+
128
+
tasks:
129
+
generate:code: # overwrites shared code task to add external API fetching
This repo contains a dummy Makefile that for any command prints the instructions for installing `task`:
144
+
```
145
+
This repository uses task (https://taskfile.dev) instead of make.
146
+
Run 'go install github.com/go-task/task/v3/cmd/task@latest' to install the latest version.
147
+
Then run 'task -l' to list available tasks.
148
+
```
149
+
150
+
To re-use it, simply create a symbolic link from the importing repo:
151
+
```shell
152
+
ln -s ./hack/common/Makefile Makefile
153
+
```
154
+
155
+
## Documentation Index Generation
156
+
157
+
This repository contains a script for creating a index for the documentation of the importing repository. This script is not executed by default, only if the `GENERATE_DOCS_INDEX` variable is explicitly set to anything except `false` in the importing Taskfile. Doing so will not only activate the documentation index generation, but also a check whether it is up-to-date during the `validate:docs` task.
158
+
159
+
⚠️ Running the documentation index generation script will overwrite the `docs/README.md` file!
160
+
161
+
The script checks the `docs` folder in the importing repository for subdirectories and markdown files (*.md) contained within. Each directory that contains a special metadata file will result in a header, followed by a list where each entry links to one of the markdown files of the respective directory. Directories without the metadata file will be ignored.
162
+
163
+
The metadata file is named `.docnames` and is expected to be JSON-formatted, containing a single object with a field named `header`. The value of this field will determine the name of the header in the documentation index for this respective folder.
164
+
165
+
Additional fields in the JSON object can be used to manipulate the entries for markdown files within the directory: An entry `"foo.md": "Bar"` in the object causes the `foo.md` file in the directory to be displayed as `Bar` in the generated index. Setting the value of such an entry to the empty string removes the corresponding file from the index.
166
+
167
+
Markdown files whose name is not overwritten by a corresponding field in the metadata file are named according to the first line starting with `# ` in their content, or ignored if the name cannot be determined this way.
168
+
169
+
#### Limitations
170
+
171
+
The script is rather primitive and can only handle a single hierarchy level, nested folder structures are not supported. Manipulating or configuring the generated index apart from adapting the names is also not possible.
12
172
13
173
## Support, Feedback, Contributing
14
174
@@ -19,7 +179,7 @@ If you find any bug that may be a security problem, please follow our instructio
19
179
20
180
## Code of Conduct
21
181
22
-
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times.
182
+
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/openmcp-project/.github/blob/main/CODE_OF_CONDUCT.md) at all times.
0 commit comments