From 77c1538822437b9528cbb0ba08a3461a9c390f6a Mon Sep 17 00:00:00 2001 From: Marian Steinbach Date: Wed, 27 Sep 2023 13:09:20 +0200 Subject: [PATCH] Move documentation into docs --- README.md | 108 ------------------------------------------ docs/development.md | 111 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+), 108 deletions(-) create mode 100644 docs/development.md diff --git a/README.md b/README.md index 221b2b2..74cad61 100644 --- a/README.md +++ b/README.md @@ -23,111 +23,3 @@ the CI. - included security: vulnerability scans for go sources, generation of SBoM, singing artifacts with `cosign` - included automated dependency updates based on [renovate](renovatebot.com) - included linting and validation for multiple types of artifacts, including golang, markdown, Kubernetes objects, ... - -### How it works - -#### Running validation and linting tools - -This repo uses [pre-commit](https://pre-commit.com/) to run a variety of static code quality analysis tools, both in -CI and local runs. Please [consult the config file](.pre-commit-config.yaml) to check what is run by default. - -The checks configured include: - -- general good practices for code files (ie. consistent line endings) -- `golang` validation based on the [golangci-lint](https://golangci-lint.run/) tool -- Dockerfile, markdown, JSON, YAML and shell scripts linting -- [gitleaks](https://github.com/gitleaks/gitleaks) tool to protect developers from committing secrets to the repo -- [helm-docs](https://github.com/norwoodj/helm-docs) to automatically generate Helm chart's README.md file with - chart's configuration options generated from `values.yaml` file - -#### Building binaries and container images - -For this purpose, the repo uses [goreleaser](https://goreleaser.com/). Please consult [its config file](.goreleaser.yaml) -to check the included configuration and tune it to your needs. - -By default, the `goreleaser` configuration includes: - -- building the go binary for 3 CPU architectures: `amd64`, `arm` and `arm64` -- building multi-architecture container image with the binary built in the previous step -- generating SBoM manifest -- signing all the artifacts with `cosign` -- creating a GitHub release with automated changelog based on git commits - -#### Building a Helm chart - -To run a set of code linting and validation tools, the setup uses -[app-build-suite](https://github.com/giantswarm/app-build-suite/). The build process includes - -- [ct](https://github.com/helm/chart-testing) Helm chart testing tool -- Kubernetes objects validation with [kube-linter](https://github.com/stackrox/kube-linter) -- actual Helm chart packaging - -### GitHub actions - -In the repo, there are already GitHub actions pre-configured. Their purpose is as follows: - -- [.github/workflows/release.yaml](.github/workflows/release.yaml): triggered on a tag push and does full project release -- [.github/workflows/validate-test.yaml](.github/workflows/validate-test.yaml): triggered on each commit, runs basic - code validation -- [.github/workflows/update-pre-commit.yaml](.github/workflows/update-pre-commit.yaml): ran on schedule to detect - automatic updates to `pre-commit` actions - -Additionally, renovate is [configured](renovate.json) to automatically handle dependencies updates. - -## Setting up local development environment - -### Minimal setup - -The `pre-commit` tools is mandatory. It will guard you from creating inconsistencies between you and other team members, -lower CI costs by limiting the necessary number of runs and even do some basic security checks. - -To install `pre-commit` and its dependencies, please refer the following docs: - -- -- -- -- obviously, a working `golang` installation - -Once you have the dependencies installed, you have to register `pre-commit` as your local hooks for the git repo -(you need to do this only once): - -```bash -pre-commit install --install-hooks -``` - -To run all the `pre-commit` checks without creating a commit, run: - -```bash -pre-commit run -a -``` - -### Setup for full build workflow - -By installing the same set of tools GitHub actions run, you can have a local dev environment that works the same -as CI/CD and provides you with faster feedback loop. - -Install additional tools: - -- [docker](https://www.docker.com/products/docker-desktop/) -- [goreleaser](https://goreleaser.com/) -- [syft](https://github.com/anchore/syft) -- [cosign](https://github.com/sigstore/cosign) -- [app-build-suite](https://github.com/giantswarm/app-build-suite/releases) - download the latest script (dockerized) - -Now, to build the go binary and docker image locally, run: - -- `goreleaser release --verbose --snapshot` - -To build the Helm chart, run: - -- `dabs.sh -c helm` - -## Creating a release - -To release a new version of an app (create a GitHub release, container image and Helm chart), create and push a tag -to trigger the process, ie. - -```bash -git tag v0.1.0 -git push origin v0.1.0 -``` diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..bb2fe3a --- /dev/null +++ b/docs/development.md @@ -0,0 +1,111 @@ +# Developing on this project + +## Setting up a local development environment + +The goal here is to have a setup that is consistent with both your colleagues' and this repositories automation, +allowing for coherence best practices and a fast feedback loop. + +### Minimal setup + +Apart from a working Golang setupo, the `pre-commit` tools is mandatory. It will guard you from creating inconsistencies +between you and other team members, lower CI costs by limiting the necessary number of runs and even do some basic +security checks. + +To install `pre-commit` and its dependencies, please refer the following docs: + +1. [Pre-commit framework installation](https://pre-commit.com/#install) +2. [golangci-lint installation](https://golangci-lint.run/usage/install/) +3. [helm-docs installation](https://github.com/norwoodj/helm-docs#installation) + +Once you have the dependencies installed, you have to register `pre-commit` as your local hooks for the git repo +(you need to do this only once): + +```nohighlight +pre-commit install --install-hooks +``` + +To run all the `pre-commit` checks without creating a commit, run: + +```nohighlight +pre-commit run -a +``` + +### Setup for full build workflow + +Install these additional tools, if you don't have them installed yet: + +- [Docker](https://www.docker.com/products/docker-desktop/) +- [GoReleaser](https://goreleaser.com/) +- [syft](https://github.com/anchore/syft) +- [Cosign](https://github.com/sigstore/cosign) +- [app-build-suite](https://github.com/giantswarm/app-build-suite/releases) - download the latest script (dockerized) + +Now, to build the Go binary and Docker image locally, run: + +```nohighlight +goreleaser release --verbose --snapshot +``` + +To build the Helm chart, run: + +```nohighlight +dabs.sh -c helm +``` + +## Creating a release + +To create a release a new version (create a GitHub release, container image and Helm chart), create and push a tag +to trigger the process, ie. + +```nohighlight +git tag v0.1.0 +git push origin v0.1.0 +``` + +Make sure to stick to the exact semver format, and always prepend the `v` for release tags. + +## Automation + +This sections provides a better understanding of what happens in GitHub workflows and pre-commit actions. + +### Running validation and linting tools + +This repo uses the [pre-commit](https://pre-commit.com/) framework to run a variety of static code quality analysis tools, +both in CI and local runs. Please [consult the config file](../.pre-commit-config.yaml) to check what is run by default. + +The checks configured include: + +- General good practices for code files (e.g. consistent line endings). +- Golang validation based on [golangci-lint](https://golangci-lint.run/). +- Syntax linting for Dockerfile, Markdown, JSON, YAML and shell scripts. +- Protection from committing secrets to the repository, using [gitleaks](https://github.com/gitleaks/gitleaks). +- Ensure up-to-date Helm chart documentation in the chart README via [helm-docs](https://github.com/norwoodj/helm-docs). + +### Building binaries, images, and charts + +For this purpose, the repo uses [goreleaser](https://goreleaser.com/). Please consult [its config file](../.goreleaser.yaml) +to check the included configuration and tune it to your needs. + +By default, the `goreleaser` configuration includes: + +- Building a Go binary for these Linux architectures: `amd64`, `arm` and `arm64`. +- Building multi-architecture container image with the binary built in the previous step. +- Generating a SBoM manifest. +- Signing all the artifacts with `cosign`. +- Creating a GitHub release with an automatically generated changelog based on git commits. + +For building a Helm chart, some code linting and validation tools are executed via +[app-build-suite](https://github.com/giantswarm/app-build-suite/). The tools applied here include +[ct](https://github.com/helm/chart-testing) and [kube-linter](https://github.com/stackrox/kube-linter). + +### GitHub workflows + +There following GitHub workflows are configured: + +- [Release project](../.github/workflows/release.yaml): triggered on a tag push to create a full project release. +- [Validate and test code](../.github/workflows/validate-test.yaml): triggered on each commit, runs basic + code validation. +- [Pre-commit auto-update](.github/workflows/update-pre-commit.yaml): ran on schedule to detect + automatic updates to `pre-commit` actions. + +Additionally, Renovate is [configured](renovate.json) to automatically handle dependency updates.