Merge pull request #593 from jmlrt/doc-improvements (#599)

Doc improvements - Reformat all `README.md` files - Fix typos and missing syntaxes) - Use Markdown implicit link names - Sort values in configuration tables - Limit lines to 80 characters (except for code blocks and tables) - Add table of content - Fix default values descriptions - Move testing instructions to `CONTRIBUTING.md` doc - Move breaking changes notices to `BREAKING_CHANGES.md` doc
elastic · jmlrt · Apr 9, 2020 · Apr 10, 2020 · Apr 10, 2020 · Apr 10, 2020
commit 6a66c2ecf53e59a45dc23249379fa5783603a5ea
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,21 +1,256 @@
-# Contributing to the Elastic helm charts
+# Contributing to the Elastic Helm charts
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Adding new features](#adding-new-features)
+- [Requirements for submiting a pull request](#requirements-for-submiting-a-pull-request)
+- [CLA (Contributor License Agreement)](#cla-contributor-license-agreement)
+- [How We Use Git and GitHub](#how-we-use-git-and-github)
+  - [Forking](#forking)
+  - [Branching](#branching)
+  - [Commits and Merging](#commits-and-merging)
+    - [Rebasing and fixing merge conflicts](#rebasing-and-fixing-merge-conflicts)
+  - [What Goes Into a Pull Request](#what-goes-into-a-pull-request)
+- [Releases](#releases)
+- [Testing](#testing)
+  - [Templating tests](#templating-tests)
+  - [Integration tests](#integration-tests)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- Use this to update TOC: -->
+<!-- docker run --rm -it -v $(pwd):/usr/src jorgeandrada/doctoc --github -->
+
+
+## Adding new features
+
+If you aren't 100% sure that this is a feature that makes sense for everyone.
+Please open an issue first to discuss with the maintainers before investing a
+lot of time into it.
+
+
+## Requirements for submiting a pull request
+
+Before submitting a pull request make sure you validated the following
+requirements:
+
+* CLA should be signed (see [CLA section][] for more details).
+
+* Charts version shouldn't be bumped (see [Releases section][] for more
+details).
+
+* Charts `README.md` should be updated if required (especially updating default
+values if they have been changed).
+
+* Templating tests should be added/updated (see [Templating tests section][] for
+more details).
+
+* Integration tests should be added/updated (see [Integration tests section][]
+for more details).
+
 
 ## CLA (Contributor License Agreement)
 
-If you haven't already you will need to sign the [CLA](https://www.elastic.co/contributor-agreement) before your pull request can be reviewed and merged.
+Please make sure you have signed our [Contributor License Agreement][]. We are
+not asking you to assign copyright to us, but to give us the right to distribute
+your code without restriction. We ask this of all contributors in order to
+assure our users of the origin and continuing existence of the code.
+You only need to sign the CLA once.
 
-## Version bumps
 
-Just like with the rest of the stack, all versions in this helm chart repo are bumped and released at the same time. There is no need to bump the version in your pull request.
+## How We Use Git and GitHub
 
-## Testing and documentation
+### Forking
 
-When making any changes be sure to also update the following:
+We follow the [GitHub forking model][] for collaborating on Helm charts code.
+This model assumes that you have a remote called `upstream` which points to the
+official Kibana repo, which we'll refer to in later code snippets.
 
-* Charts README.md
-* The templating tests which can be found in `${CHART}/tests/*.py`. [Example](/elasticsearch/tests/elasticsearch_test.py)
-* The integration tests which can be found in `${CHART}/examples/*/test/goss.yaml`. [Example](/elasticsearch/examples/default/test/goss.yaml)
+### Branching
+
+* All work on the next major release (`8.0.0`) goes into master.
+* Past major release branches are named `{majorVersion}.x`. They contain work
+that will go into the next minor release. For example, if the next minor release
+is `7.8.0`, work for it should go into the `7.x` branch.
+* Past minor release branches are named `{majorVersion}.{minorVersion}`. They
+contain work that will go into the next patch release. For example, if the next
+patch release is `7.7.1`, work for it should go into the `7.7` branch.
+* All work is done on feature branches and merged into one of these branches.
+* Where appropriate, we'll backport changes into older release branches.
+
+### Commits and Merging
+
+* Feel free to make as many commits as you want, while working on a branch.
+* Please use your commit messages to include helpful information on your
+changes and an explanation of *why* you made the changes that you did.
+* Resolve merge conflicts by rebasing the target branch over your feature
+branch, and force-pushing (see below for instructions).
+* When merging, we'll squash your commits into a single commit.
+
+#### Rebasing and fixing merge conflicts
+
+Rebasing can be tricky, and fixing merge conflicts can be even trickier because
+it involves force pushing. This is all compounded by the fact that attempting to
+push a rebased branch remotely will be rejected by git, and you'll be prompted
+to do a `pull`, which is not at all what you should do (this will really mess up
+your branch's history).
+
+Here's how you should rebase master onto your branch, and how to fix merge
+conflicts when they arise.
+
+First, make sure master is up-to-date.
+
+```shell
+git checkout master
+git fetch upstream
+git rebase upstream/master
+```
+
+Then, check out your branch and rebase master on top of it, which will apply all
+of the new commits on master to your branch, and then apply all of your branch's
+new commits after that.
+
+```shell
+git checkout name-of-your-branch
+git rebase master
+```
+
+You want to make sure there are no merge conflicts. If there are merge
+conflicts, git will pause the rebase and allow you to fix the conflicts before
+continuing.
+
+You can use `git status` to see which files contain conflicts. They'll be the
+ones that aren't staged for commit. Open those files, and look for where git has
+marked the conflicts. Resolve the conflicts so that the changes you want to make
+to the code have been incorporated in a way that doesn't destroy work that's
+been done in master. Refer to master's commit history on GitHub if you need to
+gain a better understanding of how code is conflicting and how best to resolve
+it.
+
+Once you've resolved all of the merge conflicts, use `git add -A` to stage them
+to be committed, and then use `git rebase --continue` to tell git to continue
+the rebase.
+
+When the rebase has completed, you will need to force push your branch because
+the history is now completely different than what's on the remote. **This is
+potentially dangerous** because it will completely overwrite what you have on
+the remote, so you need to be sure that you haven't lost any work when resolving
+merge conflicts. (If there weren't any merge conflicts, then you can force push
+without having to worry about this.)
+
+```
+git push origin name-of-your-branch --force
+```
+
+This will overwrite the remote branch with what you have locally. You're done!
+
+**Note that you should not run `git pull`**, for example in response to a push
+rejection like this:
+
+```
+! [rejected] name-of-your-branch -> name-of-your-branch (non-fast-forward)
+error: failed to push some refs to 'https://github.com/YourGitHubHandle/kibana.git'
+hint: Updates were rejected because the tip of your current branch is behind
+hint: its remote counterpart. Integrate the remote changes (e.g.
+hint: 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+```
+
+Assuming you've successfully rebased and you're happy with the code, you should
+force push instead.
+
+### What Goes Into a Pull Request
+
+* Please include an explanation of your changes in your PR description.
+* Links to relevant issues, external resources, or related PRs are very
+important and useful.
+* Please update any tests that pertain to your code, and add new tests where
+appropriate.
+* See [Submitting a Pull Request](#submitting-a-pull-request) for more info.
+
+
+## Releases
+
+Just like with the rest of the stack, all versions in this helm chart repo are
+bumped and released at the same time. There is no need to bump the version in
+your pull request.
+
+Charts are released from version branchs (example `7.7` branch).
+
+[Elastic Helm repository][] is updated only during releases.
+
+The current release process is documented in [release.md][].
+
+
+## Testing
+
+### Templating tests
+
+Templating tests which can be found in `${CHART}/tests/*.py`
+([Example][templating test example]).
+
+These charts use [pytest][] to test the templating logic. The dependencies for
+testing can be installed from the [requirements.txt][] in the parent directory:
+
+```
+pip install -r ./requirements.txt
+```
+
+Tests can then be run from each chart directory using `make pytest`
+
+You can also use `make template` (equivalent to `helm template` ) to look at the
+YAML being generated:
+
+It is possible to run all of the tests and linting inside of a Docker container
+using `make test`
+
+Note that templating tests are formated using [Black][], you should run
+`make lint-python` (equivalent to `black --diff --check .` ) to validate them or
+`black .` to apply formatting before submitting a pull request which will modify
+them.
+
+### Integration tests
+
+Integration tests which can be found in `${CHART}/examples/*/test/goss.yaml`
+([Example][integration test example]).
+
+Integration tests are run using [goss][] which is a [Serverspec][] like tool
+written in golang. See [integration test example][] for an example of what the
+tests look like.
+
+The different integration tests are present in each chart's `examples`
+directory.
+
+Each charts contains an `examples/default` integration test which validate the
+chart deployment with default values.
+
+`examples` directory contains also integration tests for other use cases (for
+example: using `oss` Docker images, using `6.x` version or using `security` ).
+
+Every directory which contains some `test` subdirectory is an integration test
+(`examples` directory contains also some configuration examples for some
+specific scenarios without tests like configuration for specific k8s providers).
+
+To run the goss tests against the default example:
+
+```
+cd examples/default
+make goss
+```
 
-## Adding new features
 
-If you aren't 100% sure that this is a feature that makes sense for everyone. Please open an issue first to discuss with the maintainers before investing a lot of time into it. 
+[black]: https://black.readthedocs.io/en/stable/
+[cla section]: #cla-contributor-license-agreement
+[contributor license agreement]: https://www.elastic.co/contributor-agreement
+[elastic helm repository]: https://helm.elastic.co
+[github forking model]: https://help.github.com/articles/fork-a-repo/
+[goss]: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md
+[integration test example]: https://github.com/elastic/helm-charts/blob/7.7/elasticsearch/examples/default/test/goss.yaml
+[integration tests section]: #integration-tests
+[pytest]: https://docs.pytest.org/en/latest/
+[serverspec]: https://serverspec.org
+[templating test example]: https://github.com/elastic/helm-charts/blob/7.7/elasticsearch/tests/elasticsearch_test.py
+[templating tests section]: #templating-tests
+[release.md]: https://github.com/elastic/helm-charts/blob/master/helpers/release.md
+[releases section]: #releases
+[requirements.txt]: https://github.com/elastic/helm-charts/blob/7.7/requirements.txt
diff --git a/README.md b/README.md
@@ -2,26 +2,40 @@
 
 [![Build Status](https://img.shields.io/jenkins/s/https/devops-ci.elastic.co/job/elastic+helm-charts+7.7.svg)](https://devops-ci.elastic.co/job/elastic+helm-charts+7.7/)
 
-This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.
+This functionality is in beta and is subject to change. The design and code is
+less mature than official GA features and is being provided as-is with no
+warranties. Beta features are not subject to the support SLA of official GA
+features.
 
 ## Charts
 
-Please look in the chart directories for the documentation for each chart. These helm charts are designed to be a lightweight way to configure our official docker images. Links to the relevant docker image documentation has also been added below.
+Please look in the chart directories for the documentation for each chart. These
+Helm charts are designed to be a lightweight way to configure our official
+Docker images. Links to the relevant Docker image documentation has also been
+added below.
 
 | Chart                                      | Docker documentation                                                            |
-| ------------------------------------------ | ------------------------------------------------------------------------------- |
+|--------------------------------------------|---------------------------------------------------------------------------------|
+| [APM-Server](./apm-server/README.md)       | https://www.elastic.co/guide/en/apm/server/current/running-on-docker.html       |
 | [Elasticsearch](./elasticsearch/README.md) | https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html     |
+| [Filebeat](./filebeat/README.md)           | https://www.elastic.co/guide/en/beats/filebeat/current/running-on-docker.html   |
 | [Kibana](./kibana/README.md)               | https://www.elastic.co/guide/en/kibana/current/docker.html                      |
 | [Logstash](./logstash/README.md)           | https://www.elastic.co/guide/en/logstash/current/docker.html                    |
-| [Filebeat](./filebeat/README.md)           | https://www.elastic.co/guide/en/beats/filebeat/current/running-on-docker.html   |
 | [Metricbeat](./metricbeat/README.md)       | https://www.elastic.co/guide/en/beats/metricbeat/current/running-on-docker.html |
-| [APM-Server](./apm-server/README.md)       | https://www.elastic.co/guide/en/apm/server/current/running-on-docker.html       |
 
 ## Kubernetes Versions
 
-The charts are [currently tested](https://devops-ci.elastic.co/job/elastic+helm-charts+7.7/) against all GKE versions available. The exact versions are defined under `KUBERNETES_VERSIONS` in [helpers/matrix.yml](/helpers/matrix.yml)
+The charts are [currently tested][] against all GKE versions available. The
+exact versions are defined under `KUBERNETES_VERSIONS` in
+[helpers/matrix.yml][].
 
 ## Helm versions
 
-While we are checking backward compatibility, the charts are only tested with Helm version mentioned in [helm-tester Dockerfile](helpers/helm-tester/Dockerfile) (currently 2.16.6).
-Note that we don't support [Helm 3](https://v3.helm.sh/) version.
+While we are checking backward compatibility, the charts are only tested with
+Helm version mentioned in [helm-tester Dockerfile][] (currently 2.16.6).
+Note that we don't support [Helm 3][] version.
+
+[currently tested]: https://devops-ci.elastic.co/job/elastic+helm-charts+7.7/
+[helm 3]: https://v3.helm.sh
+[helm-tester Dockerfile]: https://github.com/elastic/helm-charts/blob/7.7/helpers/helm-tester/Dockerfile
+[helpers/matrix.yml]: https://github.com/elastic/helm-charts/blob/7.7/helpers/matrix.yml