From a318ef65fddf66b44c468d4a2636930ef39a88fd Mon Sep 17 00:00:00 2001 From: Nicholas openSUSE Software Engineer Date: Wed, 20 Mar 2024 15:36:03 -0300 Subject: [PATCH] [release-v2.8] propagation for documentation-improvement from dev-v2.9 (#3681) --- README.md | 123 +++++++++++++++++++++++++++++++++---------- docs/developing.md | 25 ++++++--- docs/experimental.md | 12 +++-- docs/makefile.md | 9 +++- docs/packages.md | 9 +++- docs/validation.md | 10 +++- 6 files changed, 145 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index d69b7cb8c5..34e0d4645e 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,31 @@ This repository contains Helm charts served by Rancher Apps & Marketplace. +- More information on `how to make changes` to this repository: [`docs/developing.md`](docs/developing.md). +- More information on `experimental features`: [`docs/experimental.md`](docs/experimental.md). +- More information on `commands` that can be run in this repository: [`docs/makefile.md`](docs/makefile.md). +- More information on `Packages`: [`docs/packages.md`](docs/packages.md). +- More information on `CI validation`: [`docs/validation.md`](docs/validation.md). +- [Issues](#issues) +- [Branches](#branches) +- [Making Changes](#making-changes) +- [Adding Net-New dependencies to dev-v2.X](#adding-net-new-dependencies-to-dev-2x) +- [Versioning Charets](#versioning-charts) +- [Upstream Charts](#upstream-charts) +- [Local Charts](#local-charts) +- [Rancher Version Annotations](#rancher-version-annotations) +- [Versioning FAQ](#versioning-faq) +- [Supporting Images in Airgap](#supporting-images-in-airgap) + +--- + +### Issues + +All issues must be created in the [`rancher/rancher`](https://github.com/rancher/rancher) repository. + ### Branches -- `dev-2.X` branches contain charts that under active development, to be released in an upcoming Rancher release. +- `dev-2.X` branches contain charts that are under active development, to be released in an upcoming Rancher release. - `release-v2.X` branches contain charts that have already been developed, tested, and released on an existing Rancher release. ### Making Changes @@ -15,57 +37,79 @@ Since this repository uses [`rancher/charts-build-scripts`](https://github.com/r 3. [CI] Running `make validate` to ensure that all generated assets are up-to-date and ready to be merged. -#### Adding Net-New dependencies to dev-2.7 +#### Adding Net-New dependencies to dev-2.x A new build artifact was introduced in v2.7.0 of Rancher, titled `rancher-image-origins.txt`, which denotes the source code repository (github repository) of each image used in Charts and System-Charts. -When adding new dependencies to dev-2.7, a PR must first be raised and merged in the Rancher repository with the required changes to the `pkg/image/origins.go` file. This ensures that the artifact is up-to-date + +When adding new dependencies to dev-2.7+, a PR must first be raised and merged in the Rancher repository with the required changes to the `pkg/image/origins.go` file. + +This ensures that the artifact is up-to-date with the latest images, and will prevent build failures within Rancher when attempting to generate the artifact. Changes to this file are **not** required when updating versions of existing dependencies. #### Versioning Charts +Two kinds of charts exist in this repository. For each type the versioning is different. + +- upstream charts +- local charts. + +##### Upstream Charts + In this repository, all packages specify the `version` field in the `package.yaml`. -The versioning scheme roughly corresponds to the following rules (with exceptions): -- Major Version: represents the Rancher minor version these charts are being released to. +The upstream charts follow this versioning: `1.0.#+upX.Y.Z` + +`X`.`Y`.`Z` is the upstream chart's `major`.`minor`.`patch` + +The `1.0.#` versioning scheme roughly corresponds to the following rules (with exceptions): +- **Major Version**: represents the Rancher minor version these charts are being released to. - Anything less than `100`: Rancher 2.5 - `100`: Rancher 2.6 - - `101`: Rancher 2.7 - - `102`: Rancher 2.7 + - `101` and `102`: Rancher 2.7 - `103`: Rancher 2.8 + - `104`: Rancher 2.9 - etc. -- Minor Version: represents a release line of a given chart within a Rancher minor version. -- Patch Version: represents a patch to a given release line of a chart within a Rancher minor version. +- **Minor Version**: represents a release line of a given chart within a Rancher minor version. +- **Patch Version**: represents a patch to a given release line of a chart within a Rancher minor version. -As a rule of thumb, you will only ever touch this version to **increment the patch version once per Rancher patch release**. Once it has been incremented, it should not be incremented again until the next Rancher patch release, even if the chart points to an upstream that has been modified. For more information on how package versioning works, please see [`docs/developing.md`](docs/developing.md). +##### Local Charts + +- For local charts, we don't follow any complex versioning scheme. Only one `semver`, versioning scheme `x.x.x` is being followed. + #### Rancher Version Annotations -In addition to modifying the chart version, the `catalog.cattle.io/rancher-version` annotation is required for user-facing charts which show up in Rancher UI; there is no need to add the annotation to CRD charts or internal charts (like fleet). +In addition to modifying the chart version, the `catalog.cattle.io/rancher-version` annotation is required for user-facing charts that show up in Rancher UI; there is no need to add the annotation to CRD charts or internal charts (like fleet). General guidelines when releasing a new version of a user-facing chart: -1. **Ensure the chart has the annotation `catalog.cattle.io/rancher-version` with a lower and upper bound, such as `>= 2.6.0-0 < 2.7.0-0`**. This indicates that a fresh install of the chart should be allowed in any version of Rancher over `2.6.0-0` and below `2.7.0-0` line. It should be freshly installable in `2.6.0+`, but should not be freshly installable in Rancher `2.7.0+`. The lower bound is particularly useful for charts that will **not** work in an older version of Rancher, e.g. `catalog.cattle.io/rancher-version: >= 2.6.2-0 < 2.7.0-0` indicates that this chart should only be freshly installable in Rancher `2.6.2+`, but should not be freshly installable in `Rancher 2.7.0+`. - - If you do this, it is also recommended that you **modify the previously released chart to have `catalog.cattle.io/rancher-version: < 2.6.2-0`**. For instructions on how to modify existing charts, see [`docs/developing.md`](docs/developing.md). -2. **Ensure the chart has the annotation `catalog.cattle.io/kube-version` with a lower and upper bound, such as `>= 1.16.0-0 < 1.25.0-0`**. This indicates that a fresh install of the chart should be allowed in a cluster with any version of Kubernetes over `1.16.0` and below `1.25.0` line. It should be freshly installable in a `1.16.0+` cluster, but should not be freshly installable in `1.25.0+`. +1. **Ensure the chart has the annotation `catalog.cattle.io/rancher-version` with a lower and upper bound, such as `>= 2.6.0-0 < 2.7.0-0`**. + + - This indicates that a fresh install of the chart should be allowed in any version of Rancher over `2.6.0-0` and below `2.7.0-0` line. + + - It should be freshly installable in `2.6.0+`, but should not be freshly installable in Rancher `2.7.0+`. The lower bound is particularly useful for charts that will **not** work in an older version of Rancher, e.g. `catalog.cattle.io/rancher-version: >= 2.6.2-0 < 2.7.0-0` indicates that this chart should only be freshly installable in Rancher `2.6.2+`, but should not be freshly installable in `Rancher 2.7.0+`. + - If you do this, it is also recommended that you **modify the previously released chart to have `catalog.cattle.io/rancher-version: < 2.6.2-0`**. For instructions on how to modify existing charts, see [`docs/developing.md`](docs/developing.md). +2. **Ensure the chart has the annotation `catalog.cattle.io/kube-version` with a lower and upper bound, such as `>= 1.16.0-0 < 1.25.0-0`**. + - This indicates that a fresh install of the chart should be allowed in a cluster with any version of Kubernetes over `1.16.0` and below `1.25.0` line. It should be freshly installable in a `1.16.0+` cluster, but should not be freshly installable in `1.25.0+`. #### Versioning FAQ -- Do we directly backport charts to previous Rancher minor versions (e.g. make `100.x.x` available in Rancher `2.5`)? +1. Do we directly backport charts to previous Rancher minor versions (e.g. make `100.x.x` available in Rancher `2.5`)? -No, we do not. If a fix needs to go to both Rancher `2.5` and `v2.6`, we just release a new chart in each branch. Then, we forward-port the one released in the `release-v2.5` branch to `release-v2.6`. + - No, we do not. If a fix needs to go to both Rancher `2.5` and `v2.6`, we just release a new chart in each branch. Then, we forward-port the one released in the `release-v2.5` branch to `release-v2.6`. -If a fix that went into Rancher `2.6` needs to be backported to Rancher `2.5`, it will be the developer's responsibility to bump the chart version in `dev-v2.5`, copy back the changes, and release a **new** chart following the Rancher `2.5` versioning scheme to `release-v2.5`. + - If a fix that went into Rancher `2.6` needs to be backported to Rancher `2.5`, it will be the developer's responsibility to bump the chart version in `dev-v2.5`, copy back the changes, and release a **new** chart following the Rancher `2.5` versioning scheme to `release-v2.5`. -- If Rancher `2.5` releases Monitoring `14.5.100` and `16.6.0` and Rancher `2.6` releases Monitoring `100.0.0+up14.5.100` and `100.0.1+up16.6.0`, how do we prevent users from "downgrading" from `16.6.0` to `100.0.0+up14.5.100` on a `helm upgrade` after upgrading Rancher minor versions? +2. If Rancher `2.5` releases Monitoring `14.5.100` and `16.6.0` and Rancher `2.6` releases Monitoring `100.0.0+up14.5.100` and `100.0.1+up16.6.0`, how do we prevent users from "downgrading" from `16.6.0` to `100.0.0+up14.5.100` on a `helm upgrade` after upgrading Rancher minor versions? -Currently, this is unavoidable. There is an expectation that users should look at the upstream annotation on the chart version (e.g. `+upX.Y.Z`), read the Rancher minor version release notes, or consult the chart's `README.md` or `app-README.md` before performing an upgrade on their applications after migrating to a new Rancher minor version. + - Currently, this is unavoidable. There is an expectation that users should look at the upstream annotation on the chart version (e.g. `+upX.Y.Z`), read the Rancher minor version release notes, or consult the chart's `README.md` or `app-README.md` before performing an upgrade on their applications after migrating to a new Rancher minor version. -We are still looking for a better way to mitigate this kind of risk. + - We are still looking for a better way to mitigate this kind of risk. -- For Rancher version annotations, why don't we need to add the lower bound all the time? +3. For Rancher version annotations, why don't we need to add the lower bound all the time? -Each Rancher minor version has its dedicated chart release branch (e.g. `release-v2.5`, `release-v2.6`, etc.), so a chart designed for Rancher `2.6.x` will never be available or show up in Rancher `2.5.x`; therefore, we do not need to worry about setting a lower bound of `> 2.5.99-0` on all charts. + - Each Rancher minor version has its dedicated chart release branch (e.g. `release-v2.5`, `release-v2.6`, etc.), so a chart designed for Rancher `2.6.x` will never be available or show up in Rancher `2.5.x`; therefore, we do not need to worry about setting a lower bound of `> 2.5.99-0` on all charts. #### Supporting Images in Airgap @@ -106,14 +150,37 @@ images: tag: 1.7.4 ``` -### Links +#### Pull Request rules + +Please create your Pull Request title following this rule: + +``` +[dev-v2.X] +[release-v2.X] +``` + +A working example: +``` +[dev-v2.8] rancher-istio 103.2.0+up1.19.6 update +``` -For more information on how to make changes to this repository, please see [`docs/developing.md`](docs/developing.md). +- ``: The full name of the charts exactly how it is written under `/charts folder` +- ``: The full version of the chart, exactly how it is written under `release.yaml` +- ``: `update`; `remove`; `add` -For more information on experimental features, please see [`docs/experimental.md`](docs/experimental.md). +What you should keep in mind for releasing charts: -For more information on commands that can be run in this repository, please see [`docs/makefile.md`](docs/makefile.md). +##### Basics +- Each Pull Request should only modify one chart with its dependencies. -For more information on `Packages`, please see [`docs/packages.md`](docs/packages.md). +##### release.yaml +- Each chart version in release.yaml DOES NOT modify an already released chart. If so, stop and modify the versions so that it releases a net-new chart. +- Each chart version in release.yaml IS exactly 1 more patch or minor version than the last released chart version. If not, stop and modify the versions so that it releases a net-new chart. -For more information on CI, please see [`docs/validation.md`](docs/validation.md). \ No newline at end of file +##### Chart.yaml and index.yaml +- The `index.yaml` file has an entry for your new chart version. +- The `index.yaml` entries for each chart matches the `Chart.yaml` for each chart. +- Each chart has ALL required annotations + - kube-version annotation + - rancher-version annotation + - permits-os annotation (indicates Windows and/or Linux) diff --git a/docs/developing.md b/docs/developing.md index ff51d9b152..125039db51 100755 --- a/docs/developing.md +++ b/docs/developing.md @@ -1,5 +1,18 @@ ## Developer Workflow +- [Introducing a new package](#introducing-a-new-package) +- [Local Chart](#local-chart) +- [Upstream Chart Types](#upstream-chart-types) +- [Making Changes To Packages](#making-changes-to-packages) +- [Rebasing An Existing Package](#rebasing-an-existing-package) +- [Versioning Packages](#versioning-packages) +- [Version](#version) +- [PackageVersion](#packageversion) +- [Updating Dependencies And Subcharts](#updating-dependencies-and-subcharts) +- [Making Changes to Released Charts](#making-changes-to-released-charts) +- [Troubleshooting](#troubleshooting) + + ### Introducing a new package Introducing a new package usually requires two things: creating a directory under `packages` and filling in a `package.yaml`. @@ -25,7 +38,9 @@ url: local *Note: For local charts, you will also need to commit the Helm chart itself under `packages/${PACKAGE}/charts`.* -#### Upstream Chart From a Git Repository +#### Upstream Chart Types + +From a Git Repository ```yaml url: https://github.com/ORG/REPO.git @@ -36,7 +51,7 @@ subdirectory: charts/mychart # optional # packageVersion: 1 ``` -#### Upstream Chart From a Chart Archive +From a Chart Archive ```yaml url: https://github.com/ORG/REPO/releases/download/VERSION/CHART.tgz @@ -143,7 +158,7 @@ If the chart version you are currently modifying has never been released before, *Note: You should reset the packageVersion to 1 instead of 0 since the scripts will always introduce at least one change to the chart.* -### Updating Dependencies / Subcharts +### Updating Dependencies and Subcharts The scripts used to maintain this repository natively supports managing dependencies / subcharts for Helm charts. @@ -199,7 +214,3 @@ Otherwise, you are ready to make a PR! ### Troubleshooting Open up an issue on [https://github.com/rancher/charts-build-scripts](https://github.com/rancher/charts-build-scripts). - -#### Maintainers -- aiyengar2 (arvind.iyengar@suse.com) -- jiaqiluo (jiaqi.luo@suse.com) \ No newline at end of file diff --git a/docs/experimental.md b/docs/experimental.md index e392296085..812fe24cd8 100755 --- a/docs/experimental.md +++ b/docs/experimental.md @@ -1,4 +1,10 @@ -## Experimental: Caching +## Experimental + +- [Caching](#caching) +- [Using Manifest Upstreams Instead of Helm Charts](#using-manifest-upstreams-instead-of-helm-charts) +- [Performing only local or upstream validation](#performing-only-local-or-upstream-validation) + +### Caching If you specify `export USE_CACHE=1` before running the scripts, a cache will be used that is located at `.charts-build-scripts/.cache`. This cache is only used on `make prepare`, `make patch`, and `make charts`; it is intentionally disabled on `make validate`. @@ -8,7 +14,7 @@ However, currently caching is only implemented for `UpstreamOptions` that point If you would like to clean up your cache, either delete the `.charts-build-scripts/.cache` directory or run `make clean-cache`. -## Experimental: Using Manifest Upstreams (Instead of Helm Charts) +### Using Manifest Upstreams Instead of Helm Charts If your package.yaml points to an upstream that does not declare a Chart.yaml, the default behavior of the scripts is as follows: 1) Move all YAML files to `templates` @@ -27,7 +33,7 @@ This will be applied on the upstream chart before applying `make patch`, which m Note: This feature is marked as experimental since it's unclear if there are any additional requirements necessary to support edge cases around pulling upstream manifests. Please open up an issue on [https://github.com/rancher/charts-build-scripts](https://github.com/rancher/charts-build-scripts) if you have any suggestions! -## Experimental: Performing only local or upstream validation +### Performing only local or upstream validation In order to make it easier to debug issues related to a failure in `make validate`, two command-line flags were introduced. diff --git a/docs/makefile.md b/docs/makefile.md index 0965b8e4dc..b656951822 100755 --- a/docs/makefile.md +++ b/docs/makefile.md @@ -1,5 +1,12 @@ ## Makefile +- [Basic Commands](#basic-commands) +- [Package Commands](#package-commands) +- [Assets, Chart, and Index Commands](#assets,-chart,-and-index-commands) +- [CI Commands](#ci-commands) +- [Docs and Scripts Commands](#docs-and-scripts-commands) +- [Advanced Commands](#advanced-commands) + ### Basic Commands `make pull-scripts`: Pulls in the version of the `charts-build-scripts` indicated in scripts. @@ -36,7 +43,7 @@ Please see [`docs/validation.md`](validation.md) for more information on how CI `make template`: Updates the current directory by applying the configuration.yaml on [upstream Go templates](https://github.com/rancher/charts-build-scripts/tree/master/templates/template) to pull in the most up-to-date docs, scripts, etc. from [rancher/charts-build-scripts](https://github.com/rancher/charts-build-scripts). -### Advanced and Misc. Commands +### Advanced Commands `make list`: Prints the list of all packages tracked in the current repository and recognized by the scripts. `export PORCELAIN=1` allows you to specify that the output of this command should be script-friendly. diff --git a/docs/packages.md b/docs/packages.md index 19fd795940..7cddeab419 100755 --- a/docs/packages.md +++ b/docs/packages.md @@ -1,5 +1,11 @@ ## Packages +- [What is a Package?](#what-is-a-package?) +- [UpstreamOptions](#upstreamoptions) +- [Additional Charts CRD Options](#additional-charts-crd-options) +- [Directory Structure](#directory-structure) + + ### What is a Package? A Package represents a grouping of one or more Helm Charts. It is declared within `packages//package.yaml` with the following spec: @@ -37,7 +43,7 @@ Charts or AdditionalCharts can provide UpstreamOptions with the following possib - Package: provide a `url: packages/` and the main Chart from that package can be pulled. You should ensure that a loop is not introduced. - Local: provide `url: local` and the package will assume the contents of `workingDir` are exactly the chart you want to use. -#### [AdditionalCharts] CRDOptions +#### Additional Charts CRD Options AdditionalCharts can provide CRDOptions instead of UpstreamOptions. These CRDOptions allow the scripts to automatically construct a CRD chart from your main Chart's contents based on the template provided. @@ -73,4 +79,3 @@ packages/ templates/ # Contains any templates. Currently only used by CRDOptions ``` - diff --git a/docs/validation.md b/docs/validation.md index fe572ac19e..5000e906cb 100755 --- a/docs/validation.md +++ b/docs/validation.md @@ -1,4 +1,10 @@ -## Repository Validation / CI +## Validation + +- [Repository CI Validation](#repository-ci-validation) +- [What is the release yaml file](#what-is-the-release-yaml-file) +- [Modifying Chart Versions That Exist In Upstream](#modifying-chart-versions-that-exist-in-upstream) + +### Repository CI Validation In order to provide a way for CI to ensure that the current state of a repository is valid and all necessary commits that produce generated changes have been run by developers, `make validate` runs a series of checks on a clean Git repository. @@ -10,7 +16,7 @@ Specifically, the workflow used by `make validate` does the following: - For any assets that exist in local but not in upstream, check if it corresponds to an entry in the `release.yaml`; if not, fail. 4. Run `make unzip`; if Git is no longer clean, fail. -### What is the release.yaml? +### What is the release yaml file The `release.yaml` is only specified if `validate.url` and `validate.branch` are provided in the repository's `configuration.yaml`. It is created automatically if you run `make validate`, which will produce a list of assets that have been modified based on your upstream repository.