cd/docs/developer-guide/development-cycle.md

The Development Cycle

Prerequisites

1. Development Environment
2. Toolchain Guide

Preface

When you have developed and possibly manually tested the code you want to contribute, you should ensure that everything builds correctly. Commit your changes locally and perform the following steps, for each step the commands for both local and virtualized toolchain are listed.

Docker privileges for virtualized toolchain users

These instructions are relevant for most of the steps below

Using Podman for virtualized toolchain users

These instructions are relevant for most of the steps below

Development cycle steps

Set kubectl context to cd namespace

Setting kubectl config to the cd namespace is required for these steps to succeed. All following commands in this guide assume the namespace is already set.

kubectl config set-context --current --namespace=cd

Pull in all UI build dependencies

As build dependencies change over time, you have to synchronize your development environment with the current specification. In order to pull in all required UI dependencies (NPM packages), issue:

• make dep-ui or make dep-ui-local

These commands run pnpm install --frozen-lockfile command, which only brings package versions that are defined in the pnpm-lock.yaml file without trying to resolve and download new package versions.

Updating UI build dependencies

If you need to add new UI dependencies or update existing ones you need to run a pnpm command in the ./ui directory to resolve and download new packages.

You can run it in the docker container using the make run-pnpm make target.

For example, to add new dependency newpackage you may run command like

make run-pnpm PNPM_COMMAND="add newpackage --ignore-scripts"

To upgrade an existing package:

make run-pnpm PNPM_COMMAND="update [email protected] --ignore-scripts"

Please consider using best security practices when adding or upgrading NPM dependencies, such as this guide.

Generate API glue code and other assets

Hanzo CD relies on Google's Protocol Buffers for its API, and this makes heavy use of auto-generated glue code and stubs. Whenever you touched parts of the API code, you must re-generate the auto generated code.

• Run make codegen or make codegen-local, this might take a while
• Check if something has changed by running git status or git diff
• Commit any possible changes to your local Git branch, an appropriate commit message would be Changes from codegen, for example.

Note

There are a few non-obvious assets that are auto-generated. You should not change the autogenerated assets, as they will be overwritten by a subsequent run of make codegen. Instead, change their source files. Prominent examples of non-obvious auto-generated code are swagger.json or the installation manifest YAMLs.

Build your code and run unit tests

After the code glue has been generated, your code should build and the unit tests should run without any errors. Execute the following statements:

• make build or make build-local
• make test or make test-local

These steps are non-modifying, so there's no need to check for changes afterward.

Lint your code base

In order to keep a consistent code style in our source tree, your code must be well-formed in accordance to some widely accepted rules, which are applied by a Linter.

The Linter might make some automatic changes to your code, such as indentation fixes. Some other errors reported by the Linter have to be fixed manually.

• Run make lint or make lint-local and observe any errors reported by the Linter
• Fix any of the errors reported and commit to your local branch
• Finally, after the Linter reports no errors, run git status or git diff to check for any changes made automatically by Lint
• If there were automatic changes, commit them to your local branch

If you touched UI code, you should also run the linter on it:

• Run make lint-ui or make lint-ui-local
• Fix any of the errors reported by it

Run end-to-end tests

The final step is running the End-to-End testsuite, which ensures that your Kubernetes dependencies are working properly. This will involve starting all the Hanzo CD components on your computer. The end-to-end tests consists of two parts: a server component, and a client component.

• First, start the End-to-End server: make start-e2e or make start-e2e-local. This will spawn a number of processes and services on your system.
• When all components have started, run make test-e2e or make test-e2e-local to run the end-to-end tests against your local services.

Below you can find a few examples of how to run specific tests.

• To run a single test with a local toolchain, you can use TEST_FLAGS="-run TestName" make test-e2e-local.
• To run a specific package, you can use make TEST_MODULE=./test/e2e/<TEST_FILE>.go test-e2e-local
• Finally, you can also try make TEST_FLAGS="-run <TEST_METHOD_NAME_REGEXP>" test-e2e-local if you want a more fine-grained control.

For more information about End-to-End tests, refer to the End-to-End test documentation.

Common Make Targets

Here are some frequently used make targets (all will run on your machine):

Local Toolchain Make Targets

• make install-tools-local - Install testing and building tools for the local toolchain
• make build-local - Build Hanzo CD binaries
• make test-local - Run unit tests
• make codegen-local - Re-generate auto generated Swagger and Protobuf (after changing API code)
• make lint-local - Run linting
• make pre-commit-local - Run pre-commit checks
• make start-e2e-local - Start server for end-to-end tests
• make test-e2e-local - Run end-to-end tests
• make serve-docs-local - Serve documentation
• make start-local - Start Hanzo CD
• make cli-local - Build Hanzo CD CLI binary

Virtualized Toolchain Make Targets

• make verify-kube-connect - Test whether the virtualized toolchain has access to your K8s cluster
• make test-tools-image - Prepare the environment of the virtualized chain
• make build - Build Hanzo CD binaries
• make test - Run unit tests
• make codegen - Re-generate auto generated Swagger and Protobuf (after changing API code)
• make lint - Run linting
• make pre-commit - Run pre-commit checks
• make start-e2e - Start server for end-to-end tests
• make test-e2e - Run end-to-end tests
• make serve-docs - Serve documentation
• make start - Start Hanzo CD

---

Congrats on making it to the end of this runbook! 🚀

For more on Hanzo CD, see GitHub Issues.