Merge pull request #103 from PennyScissors/main-source

Update README

README.md

@@ -18,7 +18,7 @@ files on top of it.
     to emit the warning `manifest_sorter.go:175: info: skipping unknown hook: "crd-install"`
     on an install or upgrade.
 
-    In addition, staritng [Helm 3.5.2](https://github.com/helm/helm/releases/tag/v3.5.2), Helm is stricter about parsing semver strings. Therefore, to ensure that your chart is deployable via Helm 3.5.2, your chart must have a semver-compliant version.
+    In addition, starting [Helm 3.5.2](https://github.com/helm/helm/releases/tag/v3.5.2), Helm is stricter about parsing semver strings. Therefore, to ensure that your chart is deployable via Helm 3.5.2, your chart must have a semver-compliant version.
 
     More information:
     * Supported Hooks: https://helm.sh/docs/topics/charts_hooks/
@@ -30,21 +30,21 @@ files on top of it.
 
 * Chart must have the following Rancher specific add-ons (More details on this below).
     * Rancher Labels & Annotations for Partners
+    * kubeVersion set in the chart's metadata
     * app-readme.md
-    * questions.yaml
+    * questions.yaml (Optional)
 
 ## Workflow
 
 ### 1. Fork the repository
 
 After forking the repository, checkout the `main-source` branch and pull the latest changes.
-Then create a new branch from it (e.g. `git checkout -b <name-of-new-branch>`) and execute 
+Then create a new branch off of `main-source` (e.g. `git checkout -b <name-of-new-branch>`) and execute
 `make` commands from next steps at the repository's root level.
 
-### 2. Track a new upstream chart as a package (**SKIP if upgrading existing package**)
+### 2. Set up your package to track an upstream chart (**SKIP if upgrading existing package**)
 
-Create a package in the `packages` directory by following this structure (Replace `{CHART_NAME}` with
+Create a directory for your package in the `packages` directory and a `package.yaml` file inside (Replace `{CHART_NAME}` for your chart's name).
-the name of the upstream chart).
 
 ```text
 partner-charts                     # Repo root level
@@ -53,22 +53,20 @@ partner-charts                     # Repo root level
         └── package.yaml           # Metadata manifest containing upstream location version
 ```
 
-Track the upstream chart by setting these values in `package.yaml`:
+Set up the following in your `package.yaml` to track your upstream chart:
 
-- `url` - the URL that references you chart's tarball hosted in a Helm repository.
+- `url` - the URL that references your upstream chart's tarball hosted in a Helm repository.
 
-- `packageVersion` - The version of the package. This is appended to your chart's version in the form `{CHART_NAME}-{VERSION}{packageVersion}.tgz` after repackaging. If omitted, the version contained in your chart will be used.
+- `packageVersion` - The version of the package. This is used along with your upstream chart's name and version to generate a filename with the format `{CHART_NAME}-{VERSION}{packageVersion}+up{VERSION}.tgz` for the package's tarball that gets generated.
 
-More information of what can be specified can be found in the [README.md](packages/README.md) within the `packages/` directory.
+  For example, an upstream chart `chart-0.1.2.tgz` and the `package.yaml` from below would generate a package with the name `chart-0.1.201+up0.1.2`.
 
-#### Example `package.yaml`
+  ```yaml
+  url: https://example.com/helm-repo/chart-0.1.2.tgz
+  packageVersion: 01
+  ```
 
-This example is repackaged as `chart-v0.1.200.tgz` after modifications are applied.
+More information of what can be specified can be found in [packages/README.md](packages/README.md).
-
-```yaml
-url: https://example.com/helm-repo/chart-v0.1.2.tgz
-packageVersion: 00
-```
 
 ### 3. Prepare for changes
 
@@ -85,11 +83,12 @@ make prepare
 Any modifications to your upstream chart like **adding the partner label** will be done in
 the auto-generated `charts` directory.
 
-If this is a new chart, add the partner label and required annotations in `packages/{CHART_NAME}/charts/Chart.yaml`:
+If this is a new chart, set the `kubeVersion` field and add the required annotations in `packages/{CHART_NAME}/charts/Chart.yaml`:
 
 ```yaml
+kubeVersion: # A SemVer range of compatible Kubernetes versions. E.g 1.18 - 1.21, >= 1.19, etc
 annotations:
-  catalog.cattle.io/certified: partner
+  catalog.cattle.io/certified: partner # Enables the "partner" badge in the UI for easier identification
   catalog.cattle.io/release-name: chart-name-here # Your chart's name in kebab-case, this is used for deployment
   catalog.cattle.io/display-name: Fancy Chart Name Here # The chart's name you want displayed in the UI
 ```
@@ -99,10 +98,8 @@ You will also need to ensure that your chart has the following files in `package
 - `app-readme.md` - Write a brief description of the app and how to use it. It's recommended to keep
 it short as the longer `README.md` in your chart will be displayed in the UI as detailed description.
 
-- `questions.yaml` - Allows you to define a set of questions that user can provide answers to.
+- `questions.yaml` - Defines a set of questions to display in the chart's installation page in order for users to
-These questions will be displayed on the chart's installation page to make it easier for a user
+answer them and configure the chart using the UI instead of modifying the chart's values file directly.
-to configure common use cases / set default values exposed by the chart's `values.yaml` so that
-users can install the chart with little effort.
 
 #### Questions Example
 
@@ -170,7 +167,7 @@ export PACKAGE={CHART_NAME} # Only need to run once
 make patch
 ```
 
-### 6. Update package to track new upstream (Maintenance)
+### 6. Update package to track a new upstream (Maintenance)
 
 There are two ways you can update a package, one is to track a new updated upstream chart
 and the other is to do small modifications/fixes.
@@ -179,23 +176,31 @@ and the other is to do small modifications/fixes.
 
 Update the `url` to reference the new upstream chart. If your chart uses `packageVersion`, reset it to `01` in `package.yaml`, in order for `PACKAGE={CHART_NAME} make prepare` to pull in the new upstream chart and apply the patch if one exists. You might need to run `PACKAGE={CHART_NAME} make patch` to ensure the patch can be applied on the new upstream. If applying the patch fails, there's currently no method for rebasing to a new upstream when the patch gets broken as a result.
 
-For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-v0.1.2.tgz`
+For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-0.1.2.tgz`
-can be updated to track the new `url: https://example.com/helm-repo/chart-v0.1.3.tgz`, and a new package 
+can be updated to track the new `url: https://example.com/helm-repo/chart-0.1.3.tgz`, and a new package
-`chart-v0.1.300.tgz` will be generated.
+`chart-0.1.301+up0.1.3.tgz` will be generated.
 
 ```yaml
-url: https://example.com/helm-repo/chart-v0.1.3.tgz
+url: https://example.com/helm-repo/chart-0.1.3.tgz
-packageVersion: 00
+packageVersion: 01
 ```
 
+Dependencies are not automatically updated when rebasing a chart, therefore the `url` of each dependency will
+need to be manually updated as well. To update the dependencies go to your package's `generated-changes` directory and
+update the `url` to reference the new dependency's upstream chart in `dependencies/{DEPENDENCY_CHART_NAME}/dependency.yaml`.
+
+Take for example, a chart `example-chart` with a postgresql 0.1.2 dependency that needs to be updated to 0.1.3. To update it
+you would need to update the `url` in `example-chart/generated-changes/dependencies/postgresql/dependency.yaml` from
+`https://example.com/helm-repo/postgresql-0.1.2.tgz` to `https://example.com/helm-repo/postgresql-0.1.3.tgz`.
+
 #### Update existing package to introduce a small change
 
 If your chart uses `packageVersion`, increase the `packageVersion` in `package.yaml` without updating the `url`. This will
 create a new version of a package tracking the same upstream chart.
 
-For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-v0.1.2.tgz`
+For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-0.1.2.tgz`
-generated a package `chart-v0.1.200.tgz`. Increasing the `packageVersion` without changing the `url`
+generated a package `chart-0.1.201+up0.1.2.tgz`. Increasing the `packageVersion` without changing the `url`
-will generate a new package `chart-v0.1.201.tgz` based off of the same upstream chart.
+will generate a new package `chart-0.1.202+up0.1.2.tgz` based off of the same upstream chart.
 
 ### 7. Test your changes