From f3240ffaa56df58ce962dd17df06d041464ab2f7 Mon Sep 17 00:00:00 2001 From: TheRealNoob Date: Fri, 22 Aug 2025 10:34:57 -0700 Subject: [PATCH] docs: add helm/CONTRIBUTING.md (#18904) Signed-off-by: TheRealNoob Signed-off-by: J Stickler Co-authored-by: J Stickler --- .../workflows/scripts/helm-tagged-release.sh | 2 +- .../workflows/scripts/helm-weekly-release.sh | 4 +- CONTRIBUTING.md | 2 +- production/helm/loki/CHANGELOG.md | 9 +-- production/helm/loki/CONTRIBUTING.md | 63 +++++++++++++++++++ production/helm/loki/README.md | 41 ++---------- production/helm/loki/README.md.gotmpl | 41 ++---------- 7 files changed, 80 insertions(+), 82 deletions(-) create mode 100644 production/helm/loki/CONTRIBUTING.md diff --git a/.github/workflows/scripts/helm-tagged-release.sh b/.github/workflows/scripts/helm-tagged-release.sh index 4a0d90eec5..c09caab850 100755 --- a/.github/workflows/scripts/helm-tagged-release.sh +++ b/.github/workflows/scripts/helm-tagged-release.sh @@ -47,7 +47,7 @@ update_yaml_node "${chart_file}" .version "${new_chart_version}" sed --in-place \ --regexp-extended \ - "s/(.*\.*)/\1\n\n## ${new_chart_version}\n\n- \[CHANGE\] Changed version of Grafana Loki to ${latest_loki_tag}/g" production/helm/loki/CHANGELOG.md + "s/## Unreleased/## Unreleased\n\n## ${new_chart_version}\n\n- \[CHANGE\] Changed version of Grafana Loki to ${latest_loki_tag}/g" production/helm/loki/CHANGELOG.md make TTY='' helm-docs diff --git a/.github/workflows/scripts/helm-weekly-release.sh b/.github/workflows/scripts/helm-weekly-release.sh index 44d0455bbb..68619326b3 100755 --- a/.github/workflows/scripts/helm-weekly-release.sh +++ b/.github/workflows/scripts/helm-weekly-release.sh @@ -101,11 +101,11 @@ update_yaml_node "${chart_file}" .version "${new_chart_version}" if ${k_release}; then sed --in-place \ --regexp-extended \ - "s/(.*\.*)/\1\n\n## ${new_chart_version}\n\n- \[CHANGE\] Changed version of Grafana Loki to ${latest_loki_tag}\n- \[CHANGE\] Changed version of Grafana Enterprise Logs to ${latest_gel_tag}/g" production/helm/loki/CHANGELOG.md + "s/## Unreleased/## Unreleased\n\n## ${new_chart_version}\n\n- \[CHANGE\] Changed version of Grafana Loki to ${latest_loki_tag}\n- \[CHANGE\] Changed version of Grafana Enterprise Logs to ${latest_gel_tag}/g" production/helm/loki/CHANGELOG.md else sed --in-place \ --regexp-extended \ - "s/(.*\.*)/\1\n\n## ${new_chart_version}/g" production/helm/loki/CHANGELOG.md + "s/## Unreleased/## Unreleased\n\n## ${new_chart_version}/g" production/helm/loki/CHANGELOG.md fi make TTY='' helm-docs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd111e61b6..bfd78272f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,7 +84,7 @@ Notice: `go get` return `package github.com/grafana/loki: no Go files in /go/src ## Contribute to helm -Please follow the [Loki Helm Chart](./production/helm/loki/README.md). +Please follow the [Loki Helm Chart CONTRIBUTING.md](./production/helm/loki/CONTRIBUTING.md). ## Dependency management diff --git a/production/helm/loki/CHANGELOG.md b/production/helm/loki/CHANGELOG.md index be3907a325..350b88ed02 100644 --- a/production/helm/loki/CHANGELOG.md +++ b/production/helm/loki/CHANGELOG.md @@ -11,17 +11,18 @@ Entries should be ordered as follows: Entries should include a reference to the pull request that introduced the change. -[//]: # ( : do not remove this line. This locator is used by the CI pipeline to automatically create a changelog entry for each new Loki release. Add other chart versions and respective changelog entries bellow this line. +## Unreleased + + + ## 6.37.0 - [FEATURE] Support separate loki ruler storage configuration [#18510](https://github.com/grafana/loki/pull/18510) - [ENHANCEMENT] Add configurable `livenessProbe` and `startupProbe` to bloom-gateway. [#18551](https://github.com/grafana/loki/pull/18551) -- [ENHANCEMENT] Add configurable `livenessProbe` and `startupProbe` for loki in bloom-builder. [#18549](https://github.com/grafana/loki/pull/18549) +- [ENHANCEMENT] Add configurable `livenessProbe` and `startupProbe` for loki in bloom-builder. [#18549](https://github.com/grafana/loki/pull/1854 - [ENHANCEMENT] Add configurable `livenessProbe` and `startupProbe` to bloom-planner. [#18552](https://github.com/grafana/loki/pull/18552) - [BUGFIX] Revert Thanos object store configuration from ruler storage config to fix compatibility issues with RuleStoreConfig that caused parsing errors during Helm upgrades. - - ## 6.36.1 - [BUGFIX] Fix missing s3 field in lokiStorageConfig templated value.[#18791](https://github.com/grafana/loki/pull/18791) diff --git a/production/helm/loki/CONTRIBUTING.md b/production/helm/loki/CONTRIBUTING.md new file mode 100644 index 0000000000..2f7ba6de9a --- /dev/null +++ b/production/helm/loki/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing to the Loki Helm Chart + +Thank you for your interest in contributing to the Loki Helm Chart! This document provides guidelines for contributing to ensure the chart remains maintainable, broadly useful, and accessible to the community. + +For general Loki project contributions, please also see the main [Contributing Guide](../../../CONTRIBUTING.md). + +## Contribution Guidelines + +### What We Welcome + +We encourage contributions that: + +- **Improve general usability**: Features that benefit the majority of users +- **Fix bugs**: Clear bug fixes with reproduction steps +- **Enhance documentation**: Better examples, clearer explanations +- **Security improvements**: Security-related enhancements +- **Performance optimizations**: Changes that improve performance broadly +- **Standards compliance**: Updates to follow Kubernetes best practices + +### What We Avoid + +To keep the chart maintainable and broadly useful, we avoid: + +- **Project-specific integrations**: Features specific to other projects that serve only a small group of users +- **Company/individual-specific requirements**: Customizations that serve only specific organizations +- **Bizarre constraints**: Unusual or overly complex requirements that don't serve the general community +- **Breaking changes**: Changes that would break existing deployments without clear migration paths + +### Decision Criteria + +When reviewing contributions, we ask: + +1. **Is this generally useful?** Does it benefit the broader community or just specific users? +2. **Is it simple and reasonable?** Does it add unnecessary complexity? +3. **Does it align with Kubernetes best practices?** Is it following established patterns? +4. **Is it maintainable?** Can the community maintain this feature long-term? + +**Important**: If your use case is highly specific to your organization, consider using the Loki chart as a subchart instead of being called directly. This allows you to customize without adding complexity to the main chart. + +## Technical Requirements + +### Before Submitting a PR + +1. **Update documentation**: Run `make helm-docs` from the repository root if you modified: + - `Chart.yaml` + - `values.yaml` + - Any template files + +2. **Update the changelog**: Add an entry to [CHANGELOG.md](./CHANGELOG.md) in the `Unreleased` section using the format: + ``` + - [CHANGE|FEATURE|BUGFIX|ENHANCEMENT] Brief description of your change, and a link to the PR number. For examples, see the CHANGELOG. + ``` + +3. **Test your changes**: The CICD workflow will run comprehensive tests, however it's a good idea to run a few "quick and dirty" tests locally before committing, as those workflows can take quite a while in comparison. + - Single binary: `helm template --values single-binary-values.yaml` + - Simple scalable: `helm template --values simple-scalable-values.yaml` + - Distributed: `helm template --values distributed-values.yaml` + +4. **Commit your changes**: Our commits follow the style of [Conventional Commits](https://www.conventionalcommits.org/). High level this looks like `: description`. For example: + - `feat(helm): add resource limits to querier` + - `fix(helm): correct service selector` + +Thank you for contributing to the Loki Helm Chart! Your contributions help make log aggregation accessible to the entire community. diff --git a/production/helm/loki/README.md b/production/helm/loki/README.md index fb99c0d243..7dd263edd8 100644 --- a/production/helm/loki/README.md +++ b/production/helm/loki/README.md @@ -20,46 +20,13 @@ Helm chart for Grafana Loki and Grafana Enterprise Logs supporting monolithic, s Find more information in the Loki Helm Chart [documentation](https://grafana.com/docs/loki/next/installation/helm). -## Contributing and releasing +## Contributing -If you made any changes to the [Chart.yaml](https://github.com/grafana/loki/blob/main/production/helm/loki/Chart.yaml) or [values.yaml](https://github.com/grafana/loki/blob/main/production/helm/loki/values.yaml) run `make helm-docs` from the root of the repository to update the documentation and commit the changed files. +Please see our [Contributing Guidelines](./CONTRIBUTING.md) for detailed information about contributing to the Loki Helm Chart. -Futhermore, please add an entry to the [CHANGELOG.md](./CHANGELOG.md) file about what you changed. This file has a header that looks like this: +## Releases -``` -[//]: # ( : do not remove this line. This locator is used by the CI pipeline to automatically create a changelog entry for each new Loki release. Add other chart versions and respective changelog entries bellow this line.) -```` - -Place your changes as a bulleted list below this header. The helm chart is automatically released once a week, at which point the `CHANGELOG.md` file will be updated to reflect the release of all changes between this header the the header of the previous version as the changes for that weeks release. For example, if the weekly release will be `1.21.0`, and the `CHANGELOG.md` file has the following entries: - -``` -[//]: # ( : do not remove this line. This locator is used by the CI pipeline to automatically create a changelog entry for each new Loki release. Add other chart versions and respective changelog entries bellow this line.) - -- [CHANGE] Changed the thing -- [FEATURE] Cool new feature - -## 1.20.0 - -- [BUGFIX] Fixed the bug -``` - -Then the weekly release will create a `CHANGELOG.md` with the following content: -``` -[//]: # ( : do not remove this line. This locator is used by the CI pipeline to automatically create a changelog entry for each new Loki release. Add other chart versions and respective changelog entries bellow this line.) - -## 1.21.0 - -- [CHANGE] Changed the thing -- [FEATURE] Cool new feature - -## 1.20.0 - -- [BUGFIX] Fixed the bug -``` - -#### Versioning - -Normally contributors need _not_ bump the version nor update the [CHANGELOG.md](https://github.com/grafana/loki/blob/main/production/helm/loki/CHANGELOG.md). A new version of the Chart will follow this cadence: +Normally, contributors need _not_ bump the Chart version. A new version of the Chart will follow this cadence: - Automatic weekly releases - Releases that coincide with Loki/GEL releases - Manual releases when necessary (ie. to address a CVE or critical bug) diff --git a/production/helm/loki/README.md.gotmpl b/production/helm/loki/README.md.gotmpl index 9934d21fcb..2bca212a01 100644 --- a/production/helm/loki/README.md.gotmpl +++ b/production/helm/loki/README.md.gotmpl @@ -10,46 +10,13 @@ Find more information in the Loki Helm Chart [documentation](https://grafana.com/docs/loki/next/installation/helm). -## Contributing and releasing +## Contributing -If you made any changes to the [Chart.yaml](https://github.com/grafana/loki/blob/main/production/helm/loki/Chart.yaml) or [values.yaml](https://github.com/grafana/loki/blob/main/production/helm/loki/values.yaml) run `make helm-docs` from the root of the repository to update the documentation and commit the changed files. +Please see our [Contributing Guidelines](./CONTRIBUTING.md) for detailed information about contributing to the Loki Helm Chart. -Futhermore, please add an entry to the [CHANGELOG.md](./CHANGELOG.md) file about what you changed. This file has a header that looks like this: +## Releases -``` -[//]: # ( : do not remove this line. This locator is used by the CI pipeline to automatically create a changelog entry for each new Loki release. Add other chart versions and respective changelog entries bellow this line.) -```` - -Place your changes as a bulleted list below this header. The helm chart is automatically released once a week, at which point the `CHANGELOG.md` file will be updated to reflect the release of all changes between this header the the header of the previous version as the changes for that weeks release. For example, if the weekly release will be `1.21.0`, and the `CHANGELOG.md` file has the following entries: - -``` -[//]: # ( : do not remove this line. This locator is used by the CI pipeline to automatically create a changelog entry for each new Loki release. Add other chart versions and respective changelog entries bellow this line.) - -- [CHANGE] Changed the thing -- [FEATURE] Cool new feature - -## 1.20.0 - -- [BUGFIX] Fixed the bug -``` - -Then the weekly release will create a `CHANGELOG.md` with the following content: -``` -[//]: # ( : do not remove this line. This locator is used by the CI pipeline to automatically create a changelog entry for each new Loki release. Add other chart versions and respective changelog entries bellow this line.) - -## 1.21.0 - -- [CHANGE] Changed the thing -- [FEATURE] Cool new feature - -## 1.20.0 - -- [BUGFIX] Fixed the bug -``` - -#### Versioning - -Normally contributors need _not_ bump the version nor update the [CHANGELOG.md](https://github.com/grafana/loki/blob/main/production/helm/loki/CHANGELOG.md). A new version of the Chart will follow this cadence: +Normally, contributors need _not_ bump the Chart version. A new version of the Chart will follow this cadence: - Automatic weekly releases - Releases that coincide with Loki/GEL releases - Manual releases when necessary (ie. to address a CVE or critical bug)