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
+98-61Lines changed: 98 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,110 +2,160 @@
2
2
3
3
Argo Helm is a collection of **community maintained** charts. Therefore we rely on you to test your changes sufficiently.
4
4
5
-
6
-
# Pull Requests
5
+
## Pull Requests
7
6
8
7
All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests. See the above stated requirements for PR on this project.
9
8
9
+
### Pull Request Title Linting
10
+
11
+
We lint the title of your pull request to ensure it follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. This is done using GitHub actions and the [action-semantic-pull-request](.github/workflows/pr-title.yml) workflow. We require the scope of the change to be included in the title. The scope should be the name of the chart you are changing. For example, if you are changing the `argo-cd` chart, the title of your pull request should be `fix(argo-cd): Fix typo in values.yaml`.
12
+
13
+
## Documentation
14
+
15
+
The documentation for each chart is generated with [helm-docs](https://github.com/norwoodj/helm-docs). This way we can ensure that values are consistent with the chart documentation.
16
+
17
+
We have a script on the repository which will execute the helm-docs docker container, so that you don't have to worry about downloading the binary etc. Simply execute the script (Bash compatible, might require sudo privileges):
18
+
19
+
```shell
20
+
./scripts/helm-docs.sh
21
+
```
22
+
23
+
> **Note**
24
+
> When creating your own `README.md.gotmpl`, don't forget to add it to your `.helmignore` file.
25
+
26
+
### Updating a chart README.md
27
+
28
+
When updating the `README.md.gotmpl` inside a chart directory you must to run the `helm-docs` script to generate the updated `README.md` file. To reiterate, you should not edit the `README.md` file manually. It will be generated by the following command:
29
+
30
+
```shell
31
+
./scripts/helm-docs.sh
32
+
```
33
+
34
+
> **Note**
35
+
> If you see changes to unrelated chart `README.md` files you may have accidentally updated a `README.md.gotmpl` file in another chart's folder unintentionally or someone else failed to run this script. Please revert those changes if you do not intend them to be a part of your pull request.
36
+
10
37
## Versioning
11
38
12
-
Each chart's version follows the [semver standard](https://semver.org/). New charts should start at version `1.0.0`, if it's considered stable. If it's not considered stable, it must be released as [prerelease](#prerelease).
39
+
Each chart's version follows the [semver standard](https://semver.org/).
40
+
41
+
New charts should start at version `1.0.0`, if it's considered stable. If it isn't considered stable, it must be released as `prerelease`.
13
42
14
43
Any breaking changes to a chart (backwards incompatible) require:
15
44
16
-
* Bump of the current Major version of the chart
17
-
* State possible manual changes for this chart version in the `Upgrading` section of the chart's `README.md.gotmpl` ([See Upgrade](#upgrades))
45
+
* Bump of the current Major version of the chart
46
+
* State possible manual changes for this chart version in the `Upgrading` section of the chart's `README.md.gotmpl`
47
+
48
+
### New Application Versions
49
+
50
+
When selecting new application versions ensure you make the following changes:
51
+
52
+
*`values.yaml`: Bump all instances of the container image version
53
+
*`Chart.yaml`: Ensure `appVersion` matches the above container image and bump `version`
54
+
55
+
Please ensure chart version changes adhere to semantic versioning standards:
56
+
57
+
* Major: Large chart rewrites, major non-backwards compatible or destructive changes
58
+
* Minor: New chart functionality (sidecars), major application updates or minor non-backwards compatible changes
59
+
* Patch: App version patch updates, backwards compatible optional chart features
18
60
19
61
### Immutability
20
62
21
63
Each release for each chart must be immutable. Any change to a chart (even just documentation) requires a version bump. Trying to release the same version twice will result in an error.
22
64
65
+
### Chart Versioning
66
+
67
+
Currently we require a chart version bump for every change to a chart, including updating information for older verions. This may change in the future.
23
68
24
69
### Artifact Hub Annotations
25
70
26
71
Since we release our charts on Artifact Hub we encourage making use of the provided chart annotations for Artifact Hub.
We want to deliver transparent chart releases for our chart consumers. Therefore we require a changelog per new chart release.
33
78
34
-
Changes on a chart must be documented in a chart specific changelog in the `Chart.yaml`[Annotation Section](https://helm.sh/docs/topics/charts/#the-chartyaml-file). For every new release the entire `artifacthub.io/changes` needs to be rewritten. Each change requires a new bullet point following the pattern `- "[{type}]: {description}"`. You can use the following template:
35
-
36
-
```
37
-
name: argo-cd
38
-
version: 3.4.1
39
-
...
40
-
annotations:
41
-
artifacthub.io/changes: |
42
-
- "[Added]: Something New was added"
43
-
- "[Changed]: Changed Something within this chart"
44
-
- "[Changed]: Changed Something else within this chart"
45
-
- "[Deprecated]: Something deprecated"
46
-
- "[Removed]: Something was removed"
47
-
- "[Fixed]: Something was fixed"
48
-
- "[Security]": Some Security Patch was included"
49
-
```
50
-
51
-
## Documentation
79
+
Changes on a chart must be documented in a chart specific changelog in the `Chart.yaml`[Annotation Section](https://helm.sh/docs/topics/charts/#the-chartyaml-file).
52
80
53
-
The documentation for each chart is done with [helm-docs](https://github.com/norwoodj/helm-docs). This way we can ensure that values are consistent with the chart documentation.
81
+
A new `artifacthub.io/changes` needs to be written covering only the changes since the previous release.
54
82
55
-
We have a script on the repository which will execute the helm-docs docker container, so that you don't have to worry about downloading the binary etc. Simply execute the script (Bash compatible, might require sudo privileges):
83
+
Each change requires a new bullet point following the pattern. See more information [Artifact Hub annotations in Helm Chart.yaml file](https://artifacthub.io/docs/topics/annotations/helm/).
56
84
57
-
```
58
-
bash scripts/helm-docs.sh
85
+
```yaml
86
+
- kind: {type}
87
+
description: {description}
59
88
```
60
89
61
-
**NOTE**: When creating your own `README.md.gotmpl`, don't forget to add it to your `.helmignore` file.
90
+
You can use the following template:
62
91
63
-
64
-
65
-
# Testing
66
-
67
-
## Testing Argo Workflows Changes
92
+
```yaml
93
+
name: argo-cd
94
+
version: 5.19.12
95
+
...
96
+
annotations:
97
+
artifacthub.io/changes: |
98
+
- kind: added
99
+
description: Something New was added
100
+
- kind: changed
101
+
description: Changed Something within this chart
102
+
- kind: changed
103
+
description: Changed Something else within this chart
104
+
- kind: deprecated
105
+
description: Something deprecated
106
+
- kind: removed
107
+
description: Something was removed
108
+
- kind: fixed
109
+
description: Something was fixed
110
+
- kind: security
111
+
description: Some Security Patch was included
112
+
```
113
+
114
+
## Testing
115
+
116
+
### Testing Argo Workflows Changes
68
117
69
118
Minimally:
70
119
71
-
```
120
+
```shell
72
121
helm install charts/argo-workflows -n argo
73
122
argo version
74
123
```
75
124
76
-
Follow this instructions for running a hello world workflow.
125
+
Follow [these](https://argoproj.github.io/argo-workflows/quick-start/#submitting-an-example-workflow) instructions for running a hello world workflow.
When raising application versions ensure you make the following changes:
125
-
126
-
-`values.yaml`: Bump all instances of the container image version
127
-
-`Chart.yaml`: Ensure `appVersion` matches the above container image and bump `version`
128
-
129
-
Please ensure chart version changes adhere to semantic versioning standards:
130
-
131
-
- Patch: App version patch updates, backwards compatible optional chart features
132
-
- Minor: New chart functionality (sidecars), major application updates or minor non-backwards compatible changes
133
-
- Major: Large chart rewrites, major non-backwards compatible or destructive changes
134
-
135
-
## Testing Charts
172
+
### Testing Charts
136
173
137
174
As part of the Continuous Integration system we run Helm's [Chart Testing](https://github.com/helm/chart-testing) tool.
138
175
139
-
The checks for this tool are stricter than the standard Helm requirements, where fields normally considered optional like `maintainer` are required in the standard spec and must be valid GitHub usernames.
176
+
The checks for Chart Testing are stricter than the standard Helm requirements. For example, fields normally considered optional like `maintainer` are required in the standard spec and must be valid GitHub usernames.
140
177
141
178
Linting configuration can be found in [ct-lint.yaml](./.github/configs/ct-lint.yaml)
142
179
143
180
The linting can be invoked manually with the following command:
144
181
145
-
```
182
+
```shell
146
183
./scripts/lint.sh
147
184
```
148
185
149
186
## Publishing Changes
150
187
151
-
Changes are automatically publish whenever a commit is merged to main. The CI job (see `./.github/workflows/publish.yml`).
188
+
Changes are automatically publish whenever a commit is merged to the `main` branch by the CI job (see `./.github/workflows/publish.yml`).
Argo Helm is a collection of **community maintained** charts for [https://argoproj.github.io](https://argoproj.github.io) projects. The charts can be added using following command:
We'd love to have you contribute! Please refer to our [contribution guidelines](CONTRIBUTING.md) for details.
17
18
19
+
### Custom resource definitions
20
+
21
+
Some users would prefer to install the CRDs _outside_ of the chart. You can disable the CRD installation of the main four charts (argo-cd, argo-workflows, argo-events, argo-rollouts) by using `--set crds.install=false` when installing the chart.
22
+
23
+
Helm cannot upgrade custom resource definitions in the `<chart>/crds` folder [by design](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations). Our CRDs have been moved to `<chart>/templates` to address this design decision.
24
+
25
+
If you are using versions of a chart that have the CRDs in the root of the chart or have elected to manage the Argo Workflows CRDs outside of the chart, please use `kubectl` to upgrade CRDs manually from [templates/crds](templates/crds/) folder or via the manifests from the upstream project repo:
If you have a security concern relating to either this project repo or an individual helm chart, please [open an issue](https://github.com/argoproj/argo-helm/issues/new/choose) or [start a discussion](https://github.com/argoproj/argo-helm/discussions/new).
21
39
22
40
### Changelog
23
41
24
-
Releases are managed independently for each helm chart, and changelogs are tracked on each release. Read more about this process [here](https://github.com/argoproj/argo-helm/blob/main/CONTRIBUTING.md#changelog).
42
+
Releases are managed independently for each helm chart, and changelogs are tracked on each release. Read more about this process [here](https://github.com/argoproj/argo-helm/blob/main/CONTRIBUTING.md#changelog).
0 commit comments