From 59f938f5834ad1239af0c3c764b685bf614e45ba Mon Sep 17 00:00:00 2001 From: Mauren Berti Date: Wed, 23 Nov 2022 16:48:58 -0500 Subject: [PATCH] Update docs formatting + small fixes. * Fix minor typos. * Change formatting where ${} was used outside code blocks to prevent TeX formatting from happening in the GitHub interface. * Removed trailing whitespace. * Updated formatting of bullet points to render bullet points in the correct indentation. --- templates/template/docs/developing.md | 63 ++++++++++++++------------- templates/template/docs/makefile.md | 12 ++--- templates/template/docs/packages.md | 2 +- templates/template/docs/validation.md | 14 +++--- 4 files changed, 46 insertions(+), 45 deletions(-) diff --git a/templates/template/docs/developing.md b/templates/template/docs/developing.md index 56b47866..ec66b718 100644 --- a/templates/template/docs/developing.md +++ b/templates/template/docs/developing.md @@ -49,49 +49,50 @@ subdirectory: charts/mychart # optional ### Making Changes To Packages As a developer making changes to a particular package, you will usually follow the following steps: + 0. If you are working with a single `Package`, set `export PACKAGE=` - - Note: This inform the scripts that you only want to make changes to a particular package. This will prevent the scripts from running commands on every package in this repository. - - Note: Starting v0.3.0 of the scripts, `PACKAGE` can refer to a nested structure, e.g. you can place packages under `packages/my-stuff/package-1` and `packages/my-stuff/package-2`. If you want to target all packages in this nested structure, set `PACKAGE=my-stuff`. If you want to target a specific package in this nested structure, set `PACKAGE=my-stuff/package-1`. It should be noted, however, that `make patch` will **only** work if you point to a specific package, so setting `PACKAGE=my-stuff` would cause it to fail. -1. If necessary, update the `version` or `packageVersion` field in the `package.yaml`. Then run `make charts` and commit the changes. - - Note: It is recommended that your commit message says something along the lines of `Bump ${PACKAGE} version to ${NEW_VERSION}`. + - Note: This informs the scripts that you only want to make changes to a particular package. This will prevent the scripts from running commands on every package in this repository. + - Note: Starting v0.3.0 of the scripts, `PACKAGE` can refer to a nested structure, e.g. you can place packages under `packages/my-stuff/package-1` and `packages/my-stuff/package-2`. If you want to target all packages in this nested structure, set `PACKAGE=my-stuff`. If you want to target a specific package in this nested structure, set `PACKAGE=my-stuff/package-1`. It should be noted, however, that `make patch` will **only** work if you point to a specific package, so setting `PACKAGE=my-stuff` would cause it to fail. +1. If necessary, update the `version` or `packageVersion` field in the `package.yaml`. Then run `make charts` and commit the changes. + - Note: It is recommended that your commit message says something along the lines of `Bump ${PACKAGE} version to ${NEW_VERSION}`. 2. Run `make prepare`. This will produce a chart under `packages/${PACKAGE}/charts` that will serve as your working copy of the chart. -3. Make modifications **directly** to the working copy of the chart in `packages/${PACKAGE}/charts`. - - Note: **Do not modify `charts/${PACKAGE}/${CHART}/${VERSION}/` directly** since it will be overridden by changes to `packages/${PACKAGE}/charts`. +3. Make modifications **directly** to the working copy of the chart in `packages/${PACKAGE}/charts`. + - Note: **Do not modify `charts/${PACKAGE}/${CHART}/${VERSION}/` directly** since it will be overridden by changes to `packages/${PACKAGE}/charts`. 4. When you are happy with your changes, run `make patch`. This will automatically construct a `packages/${PACKAGE}/generated-changes` directory after assessing your current working directory in `packages/${PACKAGE}/charts`. - - Note: **You should never directly modify `packages/${PACKAGE}/generated-changes`** unless you are trying to change `packages/${PACKAGE}/generated-changes/dependencies` to update your chart dependencies. This directory is automatically constructed / destroyed by `make patch` to save the least amount of information necessary to reconstruct your working directory on a `make prepare`. + - Note: **You should never directly modify `packages/${PACKAGE}/generated-changes`** unless you are trying to change `packages/${PACKAGE}/generated-changes/dependencies` to update your chart dependencies. This directory is automatically constructed / destroyed by `make patch` to save the least amount of information necessary to reconstruct your working directory on a `make prepare`. 5. Run `make clean` to clean up your working directory. Then, commit your changes to Git with a commit message that indicates what you have changed. - - Note: **To avoid losing unsaved changes, do not run `make clean` unless you have already ran `make patch`.** `make clean` will delete the `packages/${PACKAGE}/charts` directory, so any modifications you made to the working copy of the chart will be lost. + - Note: **To avoid losing unsaved changes, do not run `make clean` unless you have already ran `make patch`.** `make clean` will delete the `packages/${PACKAGE}/charts` directory, so any modifications you made to the working copy of the chart will be lost. 6. To test your changes, run `make charts`. This will automatically create an `assets/${PACKAGE}/${CHART}-${VERSION}.tgz`, the `charts/${PACKAGE}/${CHART}/${VERSION}/` directory, and create or modify an existing `index.yaml`. Commit these changes to Git, usually with a commit titled `make charts`. - - Note: If you push the `make charts` commit to a repository, that repository would be a valid Helm repository to serve your chart. + - Note: If you push the `make charts` commit to a repository, that repository would be a valid Helm repository to serve your chart. -If you need to make additional changes after testing, repeat steps 2-6. +If you need to make additional changes after testing, repeat steps 2-6. If your repository is configured to use upstream validation (e.g. check if `validation.url` and `validation.branch` is specified in the root `configuration.yaml`), you will also need to add this new chart's name and version to the `release.yaml` or else you will fail CI. If you run `make validate` locally, it will automatically generate this file for you. -For more information on how to do this or why this is required, please see [`docs/validation.md`](docs/validation.md). +For more information on how to do this or why this is required, please see [`docs/validation.md`](validation.md). Otherwise, you are ready to make a PR! ### Rebasing An Existing Package -For forked charts only (e.g. any chart where the `package.yaml` does not have `url: local`), currently the scripts do not have good support for rebasing charts to a new upstream. +For forked charts only (e.g. any chart where the `package.yaml` does not have `url: local`), currently the scripts do not have good support for rebasing charts to a new upstream. The reason why this is the case is that the patch files defined under `packages/${PACKAGE}/generated-changes/patch/*` are based on the old upstream, so when you change the URL it is unable to reconcile how to apply the patch. Therefore, the best way to currently rebase is to follow the following workflow: 0. Set `PACKAGE=` pointing to the specific package you want to work with. -1. If the chart has not been released yet, delete your existing charts, assets, and `index.yaml` entries corresponding to the chart you are rebasing by running `CHART= VERSION= make remove` for each chart (e.g. if you have a chart that also packages a CRD chart, you will need to run `make remove` twice for the main chart and the CRD chart). Then, commit your changes to Git with a commit message that says "Remove charts/assets for ${CHART} ${VERSION}" +1. If the chart has not been released yet, delete your existing charts, assets, and `index.yaml` entries corresponding to the chart you are rebasing by running `CHART= VERSION= make remove` for each chart (e.g. if you have a chart that also packages a CRD chart, you will need to run `make remove` twice for the main chart and the CRD chart). Then, commit your changes to Git with a commit message that says "Remove charts/assets for " 2. Without making any other changes, run `make prepare`. This will apply your existing patches on your existing upstream to produce `packages/${PACKAGE}/${workingDir}` (usually `packages/${PACKAGE}/charts`). 3. Modify the `package.yaml` to point to your new upstream. -4. Run `make patch`. This will destroy the current contents of `packages/${PACKAGE}/generated-changes` and reconstruct everything as if you were patching the new upstream with your **existing** chart. -5. Run `make clean`. Then, commit your changes to Git with a commit message that says "Rebase ${PACKAGE} from ${OLD_REF} to ${NEW_REF}"; this will make it easier for reviewers to see what you actually introduced in the next commit. +4. Run `make patch`. This will destroy the current contents of `packages/${PACKAGE}/generated-changes` and reconstruct everything as if you were patching the new upstream with your **existing** chart. +5. Run `make clean`. Then, commit your changes to Git with a commit message that says "Rebase from to "; this will make it easier for reviewers to see what you actually introduced in the next commit. 6. Follow the same developer workflow as defined under `Making Changes to Packages` to change the version, add back in changes introduced by upstream, and generate charts / assets. Once these steps are compplete, you should have something similar to the following four commits: -1. "Remove charts/assets for ${CHART} ${VERSION}" -2. "Rebase ${PACKAGE} from ${OLD_REF} to ${NEW_REF}" -3. "Add changes from rebasing ${CHART} to ${NEW_VERSION}" +1. "Remove charts/assets for " +2. "Rebase from to " +3. "Add changes from rebasing to " 4. "make charts" As a result, developers reviewing your chart can see changes made to `packages/` by reviewing changes between commit 2 and commit 3; they can also inspect changes introduced to `charts/` by viewing the overall diff on the PR, since the old assets will show as renamed / modified. @@ -100,7 +101,7 @@ You are ready to make a PR! ### Known Issue: Making Changes to the Version of an Existing Package -If you are working with a repository using `charts-build-scripts` that uses remote validation (e.g. `validate.url` and `validate.branch` are provided in the `configuration.yaml`) and you are making a change that would modify the version of an existing package (e.g. replacing a version like `0.1.2-rc3` with `0.1.2-rc4`), please see the section `Modifying Chart Versions That Exist In Upstream` within [`docs/validation.md`](docs/validation.md) for how to ensure CI still passes after making your change. +If you are working with a repository using `charts-build-scripts` that uses remote validation (e.g. `validate.url` and `validate.branch` are provided in the `configuration.yaml`) and you are making a change that would modify the version of an existing package (e.g. replacing a version like `0.1.2-rc3` with `0.1.2-rc4`), please see the section `Modifying Chart Versions That Exist In Upstream` within [`docs/validation.md`](validation.md) for how to ensure CI still passes after making your change. ### Versioning Packages @@ -108,17 +109,17 @@ Generally, repositories that are using `charts-build-scripts` use one of the fol #### Version -This versioning scheme is used if `version` is specified in the `package.yaml`. +This versioning scheme is used if `version` is specified in the `package.yaml`. -If a valid semver for `version` is provided, the final version of the chart will be the same as the `version` provided. +If a valid semver for `version` is provided, the final version of the chart will be the same as the `version` provided. -The only caveat is that **if** the main chart corresponds to some upstream chart whose chart version is not the same as the `version` provided, then the upstream version will be appended as a build annotation following the pattern `+up`. +The only caveat is that **if** the main chart corresponds to some upstream chart whose chart version is not the same as the `version` provided, then the upstream version will be appended as a build annotation following the pattern `+up`. *e.g. If `version` is 100.0.0 and the upstream chart's version is `1.2.3`, the final version will be `100.0.0+up1.2.3`.* #### PackageVersion -This versioning scheme is used if `packageVersion` is specified in the `package.yaml`. +This versioning scheme is used if `packageVersion` is specified in the `package.yaml`. If a two-digit `packageVersion` is provided, the final version of the chart that is produced under the generated assets will be the same as the version specified by the main chart in the package, except the patch version of will be `int(originalPatchVersion * 100 + packageVersion)`. @@ -132,21 +133,21 @@ Examples: You should generally update the `packageVersion` **once per release**. -If the chart version you are currently modifying has already been released before, you should **bump the `packageVersion` by 1** to ensure you aren't modifying an already released chart. +If the chart version you are currently modifying has already been released before, you should **bump the `packageVersion` by 1** to ensure you aren't modifying an already released chart. *e.g. if chart version `1.2.301` is released, bumping the `packageVersion` to `2` will result in `1.2.302` being released next.* -If the chart version you are currently modifying has never been released before, you should **reset the `packageVersion` to 1**. +If the chart version you are currently modifying has never been released before, you should **reset the `packageVersion` to 1**. -*e.g. if chart version `1.2.301` is released but you are currently working on releasing a package based on `1.3.0`, you should reset the `packageVersion` to `1` to release `1.3.1`.* +*e.g. if chart version `1.2.301` is released, but you are currently working on releasing a package based on `1.3.0`, you should reset the `packageVersion` to `1` to release `1.3.1`.* *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 -The scripts used to maintain this repository natively supports managing dependencies / subcharts for Helm charts. +The scripts used to maintain this repository natively supports managing dependencies / subcharts for Helm charts. -Subcharts can be added by creating a file under `packages/${PACKAGE}/generated-changes/dependencies/${SUBCHART}/dependency.yaml`. +Subcharts can be added by creating a file under `packages/${PACKAGE}/generated-changes/dependencies/${SUBCHART}/dependency.yaml`. The following utility script can be used to create the necessary `dependency.yaml` file in the right location: @@ -169,14 +170,14 @@ Once declared, `make prepare` will automatically pull in your dependency under ` #### Known Issue: Managed Files -In any Helm chart managed by these scripts, we consider the `Chart.yaml` / `requirements.yaml` to be `Managed Files` since they are the only files that end up going through a three-way merge. +In any Helm chart managed by these scripts, we consider the `Chart.yaml` / `requirements.yaml` to be `Managed Files` since they are the only files that end up going through a three-way merge. Specifically, the three-way merge occurs because there are three parties involved in applying changes on a `make prepare`: 1. The upstream chart source, which provides the base `Chart.yaml` / `requirements.yaml` 2. The scripts themselves, which make changes to support adding in dependencies based on those specified under `generated-changes/dependencies`. 3. The user, who commits patches to those files after running `make patch` -As a result, on updating dependencies for charts, these files are prone to having conflicts. +As a result, on updating dependencies for charts, these files are prone to having conflicts. The only workaround for this issue is to delete the patch files manually (e.g. `rm packages/${PACKAGE}/generated-changes/patch/Chart.yaml.patch` and/or `rm packages/${PACKAGE}/generated-changes/patch/requirements.yaml.patch`), run `make prepare`, and redo the patches you added to these files manually. @@ -189,7 +190,7 @@ If a chart version that you want to make changes to has already been released (i In addition, if your repository is configured to use upstream validation (e.g. check if `validation.url` and `validation.branch` is specified in the root `configuration.yaml`), you will also need to add this modified chart's name and version to the `release.yaml` or else you will fail CI. If you run `make validate` locally, it will automatically generate this file for you. -For more information on how to do this or why this is required, please see [`docs/validation.md`](docs/validation.md). +For more information on how to do this or why this is required, please see [`docs/validation.md`](validation.md). Otherwise, you are ready to make a PR! diff --git a/templates/template/docs/makefile.md b/templates/template/docs/makefile.md index 74785841..0965b8e4 100644 --- a/templates/template/docs/makefile.md +++ b/templates/template/docs/makefile.md @@ -6,15 +6,15 @@ ### Package Commands -`make prepare`: Pulls in your charts from upstream and creates a basic `generated-changes/` directory with your dependencies from upstream. By default, this prepares every `Package` in your repository but it can be scoped by providing `PACKAGE=`, where `packagePrefix` can either be 1) the exact folder in which a `package.yaml` resides in `packages/` or 2) a directory that contains multiple directories with `package.yaml` files; in the latter case, all packages in that prefix will be prepared. *If you are working with a local chart with no dependencies, this command does nothing.* +`make prepare`: Pulls in your charts from upstream and creates a basic `generated-changes/` directory with your dependencies from upstream. By default, this prepares every `Package` in your repository, but it can be scoped by providing `PACKAGE=`, where `packagePrefix` can either be 1) the exact folder in which a `package.yaml` resides in `packages/` or 2) a directory that contains multiple directories with `package.yaml` files; in the latter case, all packages in that prefix will be prepared. *If you are working with a local chart with no dependencies, this command does nothing.* `make patch`: Updates your `generated-changes/` to reflect the difference between upstream and the current working directory of your branch (note: this command should only be run after `make prepare`). Unlike `make prepare`, `PACKAGE=` must point to an exact folder in which a `package.yaml` resides in `packages/`. *If you are working with a local chart with no dependencies, this command does nothing.* `make clean`: Cleans up all the working directories of charts to get your repository ready for a PR. Supports `PACKAGE=` as defined above. *If you are working with a local chart with no dependencies, this command does nothing.* -`make charts`: Runs `make prepare` and then exports your charts to `assets/` and `charts/` and generates or updates your `index.yaml`. Supports `PACKAGE=` as defined above. +`make charts`: Runs `make prepare` and then exports your charts to `assets/` and `charts/` and generates or updates your `index.yaml`. Supports `PACKAGE=` as defined above. -Please see [`docs/developing.md`](docs/developing.md) for more information on how to use these commands in a normal developer workflow. +Please see [`docs/developing.md`](developing.md) for more information on how to use these commands in a normal developer workflow. ### Assets, Chart, and Index Commands @@ -24,13 +24,13 @@ Please see [`docs/developing.md`](docs/developing.md) for more information on ho `make zip`: Reconstructs archives in the `assets` directory based on the current contents in `charts` and updates the `charts/` contents based on the packaged archive(s). Can be scoped to specific charts via specifying `CHART={chart}` or `CHART={chart}/{version}`. Runs `make index` after reconstruction. -Please see [`docs/developing.md`](docs/developing.md) for more information on how to use these commands to modify released charts. +Please see [`docs/developing.md`](developing.md) for more information on how to use these commands to modify released charts. ### CI Commands `make validate`: Checks whether all generated assets used to serve a Helm repository (`charts/`, `assets/`, and `index.yaml`) are up-to-date. If `validate.url` and `validate.branch` are provided in the configuration.yaml, it will also ensure that any additional changes introduced only modify chart or package versions specified in the `release.yaml`; otherwise it will output the expected `release.yaml` based on assets it detected changes in. -Please see [`docs/validation.md`](docs/validation.md) for more information on how CI is performed. +Please see [`docs/validation.md`](validation.md) for more information on how CI is performed. ### Docs and Scripts Commands @@ -44,4 +44,4 @@ Please see [`docs/validation.md`](docs/validation.md) for more information on ho `make standardize`: Takes an arbitrary Helm repository (defined as any repository with a set of Helm charts under `charts/`) and standardizes it to the expected repository structure of these scripts. -`make clean-cache`: Deletes `.charts-build-scripts/.cache`. Only used if `export USE_CACHE=1` is set, which indicates that you are using the experimental caching feature introduced in v0.3.0 of the scripts. Please see [`docs/experimental.md`](docs/experimental.md) for more information. \ No newline at end of file +`make clean-cache`: Deletes `.charts-build-scripts/.cache`. Only used if `export USE_CACHE=1` is set, which indicates that you are using the experimental caching feature introduced in v0.3.0 of the scripts. Please see [`docs/experimental.md`](experimental.md) for more information. \ No newline at end of file diff --git a/templates/template/docs/packages.md b/templates/template/docs/packages.md index d3be4422..19fd7959 100644 --- a/templates/template/docs/packages.md +++ b/templates/template/docs/packages.md @@ -70,7 +70,7 @@ packages/ # Files that were overlaid onto upstream verbatim. Follows the same directory structure as the chart patch/ # Files that were patches from upstream. Follows the same directory structure as the chart and contains Unified Unix Diffs - templates/ + templates/ # Contains any templates. Currently only used by CRDOptions ``` diff --git a/templates/template/docs/validation.md b/templates/template/docs/validation.md index f9b18fbb..fe572ac1 100644 --- a/templates/template/docs/validation.md +++ b/templates/template/docs/validation.md @@ -6,8 +6,8 @@ Specifically, the workflow used by `make validate` does the following: 1. Ensure Git is clean; if not, fail. 2. Run `make charts`; if Git is no longer clean, fail and leave behind the assets. 3. **Only if `validate.url` and `validate.branch` are provided in the `configuration.yaml`**, pull in the specified Git repository, standardize the repository, and check each asset: - - For any assets that exist in upstream, check if it is modified or does not exist in local. If so, copy it over, unzip it, and fail. - - 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. + - For any assets that exist in upstream, check if it is modified or does not exist in local. If so, copy it over, unzip it, and fail. + - 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? @@ -16,14 +16,14 @@ The `release.yaml` is only specified if `validate.url` and `validate.branch` are When a GitHub repository is provided for this repository to validate against, the scripts ensure that any changes introduced to the current repository make **no additions, modifications, or deletions** to the upstream repository's `charts/`, `assets/`, or `index.yaml`. -**However, if this were the case always, we would not be able add charts or make modifications to existing charts!** +**However, if this were the case always, we would not be able to add charts or make modifications to existing charts!** -Therefore, to signal to the scripts that you are adding a new chart to upstream, making a modification to an existing chart, or removing a chart, you will need to specify the versions under `${CHART}`. +Therefore, to signal to the scripts that you are adding a new chart to upstream, making a modification to an existing chart, or removing a chart, you will need to specify the versions under `${CHART}`. For example: ```yaml -: +: - - - @@ -48,7 +48,7 @@ longhorn-crd: ### Modifying Chart Versions That Exist In Upstream -One of the caveats with using the `release.yaml` is that **renames are not supported** (e.g. you cannot remove and replace a chart in a single step). +One of the caveats with using the `release.yaml` is that **renames are not supported** (e.g. you cannot remove and replace a chart in a single step). As a result, if you attempt to modify a version of a chart that already exists in upstream, **both the old version and the new version must exist in the release.yaml for CI to pass**. Once the changes have been merged, you can later remove the old version from the release.yaml (usually as part of a release process). @@ -57,7 +57,7 @@ To give a concrete example of such a scenario, let's say that you have currently 2. You run `CHART=my-chart VERSION=0.1.2-rc3 make remove` to delete the older version of the chart 3. You run `make charts` to produce the new assets and charts for `my-chart` version `0.1.2-rc4`. 4. You modify the release.yaml to **replace** `my-chart[0] = 0.1.2-rc3` with `my-chart[0] = 0.1.2-rc4`. -4. You make a PR to your repository. +5. You make a PR to your repository. In this case, CI will fail since you are attempting to remove `0.1.2-rc3` but it is not tracked in the `release.yaml`.