Update CONTRIBUTING

- [x] versioning details
- [x] remove broken links
- [x] fix markdown linting errors
- [x] README.md updating clarification

Signed-off-by: jmeridth <jmeridth@gmail.com>
Co-authored-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

CONTRIBUTING.md

@@ -2,30 +2,41 @@
 
 Argo Helm is a collection of **community maintained** charts. Therefore we rely on you to test your changes sufficiently.
 
-
+## Pull Requests
-# Pull Requests
 
 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.
 
 ## Versioning
 
-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).
+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 isn't considered stable, it must be released as `prerelease`.
 
 Any breaking changes to a chart (backwards incompatible) require:
 
-  * Bump of the current Major version of the chart
+* Bump of the current Major version of the chart
-  * State possible manual changes for this chart version in the `Upgrading` section of the chart's `README.md.gotmpl` ([See Upgrade](#upgrades))
+* State possible manual changes for this chart version in the `Upgrading` section of the chart's `README.md.gotmpl`
+
+### Updating a chart README.md
+
+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:
+
+```shell
+./scripts/helm-docs.sh
+```
+
+> **Note**
+> 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.
 
 ### Immutability
 
 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.
 
-
 ### Artifact Hub Annotations
 
 Since we release our charts on Artifact Hub we encourage making use of the provided chart annotations for Artifact Hub.
 
-  * [https://artifacthub.io/docs/topics/annotations/helm/](https://artifacthub.io/docs/topics/annotations/helm/)
+* [https://artifacthub.io/docs/topics/annotations/helm/](https://artifacthub.io/docs/topics/annotations/helm/)
 
 #### Changelog
 
@@ -33,12 +44,12 @@ We want to deliver transparent chart releases for our chart consumers. Therefore
 
 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:
 
-```
+```yaml
 name: argo-cd
 version: 3.4.1
 ...
 annotations:
-  artifacthub.io/changes: |
+artifacthub.io/changes: |
     - "[Added]: Something New was added"
     - "[Changed]: Changed Something within this chart"
     - "[Changed]: Changed Something else within this chart"
@@ -54,59 +65,58 @@ The documentation for each chart is done with [helm-docs](https://github.com/nor
 
 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):
 
-```
+```shell
 bash scripts/helm-docs.sh
 ```
 
 **NOTE**: When creating your own `README.md.gotmpl`, don't forget to add it to your `.helmignore` file.
 
+## Testing
 
-
+### Testing Argo Workflows Changes
-# Testing
-
-## Testing Argo Workflows Changes
 
 Minimally:
 
-```
+```shell
 helm install charts/argo-workflows -n argo
 argo version
 ```
 
 Follow this instructions for running a hello world workflow.
 
-## Testing Argo CD Changes
+### Testing Argo CD Changes
 
 Clean-up:
 
-```
+```shell
 helm delete argo-cd --purge
 kubectl delete crd -l app.kubernetes.io/part-of=argocd
 ```
 
 Pre-requisites:
-```
+
+```shell
 helm repo add redis-ha https://dandydeveloper.github.io/charts/
 helm dependency update
 ```
 
 Minimally:
 
-```
+```shell
 helm install argocd  argo/argo-cd  -n argocd --create-namespace
 kubectl port-forward service/argo-cd-argocd-server -n argocd 8080:443
 ```
 
 In a new terminal:
 
-```
+```shell
 argocd version --server localhost:8080 --insecure
 # reset password to 'Password1!'
 kubectl -n argocd patch secret argocd-secret \
-  -p '{"stringData": {
+-p '{"stringData": {
     "admin.password": "$2a$10$hDj12Tw9xVmvybSahN1Y0.f9DZixxN8oybyA32Uy/eqWklFU4Mo8O",
     "admin.passwordMtime": "'$(date +%FT%T%Z)'"
-  }}'
+}}'
 argocd login localhost:8080 --username admin --password 'Password1!'
 
 # WARNING: server certificate had error: x509: certificate signed by unknown authority. Proceed insecurely (y/n)? y
@@ -114,25 +124,25 @@ argocd login localhost:8080 --username admin --password 'Password1!'
 
 Create and sync app:
 
-```
+```shell
 argocd app create guestbook --dest-namespace default --dest-server https://kubernetes.default.svc --path guestbook --project default --repo https://github.com/argoproj/argocd-example-apps.git
 argocd app sync guestbook
 ```
 
-## New Application Versions
+### New Application Versions
 
 When raising application versions ensure you make the following changes:
 
-- `values.yaml`: Bump all instances of the container image version
+* `values.yaml`: Bump all instances of the container image version
-- `Chart.yaml`: Ensure `appVersion` matches the above container image and bump `version`
+* `Chart.yaml`: Ensure `appVersion` matches the above container image and bump `version`
 
 Please ensure chart version changes adhere to semantic versioning standards:
 
-- Patch: App version patch updates, backwards compatible optional chart features
+* Patch: App version patch updates, backwards compatible optional chart features
-- Minor: New chart functionality (sidecars), major application updates or minor non-backwards compatible changes
+* Minor: New chart functionality (sidecars), major application updates or minor non-backwards compatible changes
-- Major: Large chart rewrites, major non-backwards compatible or destructive changes
+* Major: Large chart rewrites, major non-backwards compatible or destructive changes
 
-## Testing Charts
+### Testing Charts
 
 As part of the Continuous Integration system we run Helm's [Chart Testing](https://github.com/helm/chart-testing) tool.
 
@@ -142,7 +152,7 @@ Linting configuration can be found in [ct-lint.yaml](./.github/configs/ct-lint.y
 
 The linting can be invoked manually with the following command:
 
-```
+```shell
 ./scripts/lint.sh
 ```