### Example GET Request

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Demonstrates how to make a GET request to the /get endpoint and view the response headers and body.

```bash
curl localhost:8080/get
```

--------------------------------

### Setup Diagd Virtual Environment

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Instructions for setting up a Python virtual environment to work on 'diagd'. This includes creating the environment, activating it, installing dependencies, and performing an editable installation of the ambassador package.

```bash
# Create a virtualenv named venv with all the python requirements
# installed.
python3 -m venv venv
. venv/bin/activate
# If you're doing this in Datawire's apro.git, then:
cd ambassador
# Update pip and install dependencies
pip install --upgrade pip
pip install orjson    # see below
pip install -r builder/requirements.txt
# Created an editable installation of ambassador:
pip install -e python/
# Check that we do indeed have diagd in our path.
which diagd
# If you're doing this in Datawire's apro.git, then:
cd ..
```

--------------------------------

### Example Hello Request

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Demonstrates how to make a request to the /hello endpoint and view the response.

```bash
curl localhost:8080/hello
```

--------------------------------

### Start Ambex with configuration directory

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Starts the ambex service, loading configuration from the specified directory. Use the --watch flag to enable automatic reloading on file changes.

```shell
go run github.com/datawire/ambassador/cmd/busyambassador ambex ./example/ambex/
```

```shell
go run github.com/datawire/ambassador/cmd/busyambassador ambex --watch ./example/ambex/
```

--------------------------------

### Test Website Changes Locally

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Before submitting a pull request, you can test your website changes locally. Run `yarn install` to install dependencies, then `yarn start` to launch the local development server. Access the site at `localhost:8000`.

```bash
yarn install && yarn start
```

--------------------------------

### Run Full E2E Test Cycle

Source: https://github.com/emissary-ingress/emissary/blob/main/test/e2e/README.md

Execute the complete end-to-end testing cycle, including cluster setup, image building, Emissary installation, and test execution.

```bash
make e2e/local
```

--------------------------------

### Generate and Report Dependencies

Source: https://github.com/emissary-ingress/emissary/blob/main/tools/src/py-mkopensource/README.md

Installs requirements, generates a dependency list using `pip show`, and then processes it with `py-mkopensource`. The output is piped directly to the tool.

```shell
pip3 --disable-pip-version-check install -r requirements.txt
pip3 --disable-pip-version-check freeze --exclude-editable | cut -d= -f1 | xargs pip show | sed 's/^---$//' >dependenncies.txt
echo '' >>dependenncies.txt
cat dependenncies.txt | ./py-mkopensource
```

--------------------------------

### Start Envoy with ADS bootstrap configuration

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Launches an Envoy proxy instance with a bootstrap configuration that points to the ADS service. Ensure the Envoy configuration file is correctly set up.

```shell
envoy -l debug -c ./example/envoy/bootstrap-ads.yaml
```

--------------------------------

### WebSocketMapping Variant Example

Source: https://github.com/emissary-ingress/emissary/blob/main/python/tests/src/tests/README.md

This example shows how to define a `WebSocketMapping` as a subclass of `MappingTest`. It iterates through different `ServiceType` variants to create new instances with appropriate names.

```python
class WebSocketMapping(MappingTest):
    ...

    @classmethod
    def variants(cls):
        for st in variants(ServiceType):
            yield cls(st, name="{self.target.name}")
```

--------------------------------

### Open Envoy Build Container Shell

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Starts the Envoy build container and opens an interactive bash shell session. The '_cxx/envoy' directory is volume-mounted, and the user is set to 'envoybuild' for hermetic builds.

```shell
make envoy-shell
```

--------------------------------

### Creating Release Branch

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Create a new branch for the release. Do not name branches starting with 'release/'.

```bash
git checkout -b rel/0.84.0
```

--------------------------------

### Adding a custom linter to 'make lint'

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/intro.md

Integrate a custom linter like 'flake8' into the 'make lint' target. This example shows how to define a separate rule for the linter and then depend on it from the 'lint' target.

```makefile
lint: flake8
flake8:
	flake8 mypackage/
.PHONY: flake8
```

--------------------------------

### Tagging Master for RC Release

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Tag the master branch with a release candidate tag. This tag must start with 'v'.

```bash
git tag v0.77.0-rc.1 master
git push --tags origin master
```

--------------------------------

### Build Emissary-ingress within a Docker Container

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

This sequence of commands allows building Emissary-ingress inside a Docker container, leveraging Docker-in-Docker. It includes pulling the Docker image, running it with volume mounting for the Docker socket, installing build dependencies, cloning the repository, and initiating the build.

```bash
docker pull docker:latest
```

```bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -it docker:latest sh
```

```bash
apk add --update --no-cache bash build-base go curl rsync python3 python2 git libarchive-tools gawk jq
```

```bash
git clone https://github.com/emissary-ingress/emissary.git && cd emissary
```

```bash
make images
```

--------------------------------

### Tagging for GA Release

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Tag the release branch with a GA tag. This tag must start with 'v'. CI will then retag the latest RC image as the GA image.

```bash
git tag v0.77.0
```

--------------------------------

### Build Targets

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Use 'make help' and 'make targets' to discover available build targets and their documentation.

```bash
make help
```

```bash
make targets
```

--------------------------------

### Set Up Development Environment for Testing

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Before running tests, set the `DEV_REGISTRY` and `DEV_KUBECONFIG` environment variables. Ensure you are logged into your development Docker registry and have the necessary permissions.

```bash
export DEV_REGISTRY=<your-dev-docker-registry>
```

```bash
export DEV_KUBECONFIG=<your-dev-kubeconfig>
```

--------------------------------

### Get Emissary LoadBalancer IP Address (GKE/Azure)

Source: https://github.com/emissary-ingress/emissary/blob/main/charts/emissary-ingress/templates/NOTES.txt

For GKE and Azure, use this command to get the LoadBalancer IP address. Note that it may take a few minutes for the IP to become available.

```bash
export SERVICE_IP=$(kubectl get svc --namespace {{ include "ambassador.namespace" .}} {{ include "ambassador.fullname" . }} -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo http://$SERVICE_IP:{{ .Values.service.port }}
```

--------------------------------

### Preparing Release Notes

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Use `make release-prep` to update CHANGELOG.md. This command will prompt for release notes, which should be pasted in during the make process.

```bash
make release-prep
```

--------------------------------

### Minimal MappingTest Instantiation

Source: https://github.com/emissary-ingress/emissary/blob/main/python/tests/src/tests/README.md

This demonstrates the minimal way to instantiate a `MappingTest` by providing an HTTP echo service as the target.

```python
MappingTest(HTTP())
```

--------------------------------

### Change Loglevel at Runtime

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Adjust the log level for diagd and Envoy by sending a GET request to the diagnostic endpoint. Note that this does not affect the AES amb-sidecar.

```console
curl localhost:8877/ambassador/v0/diag/?loglevel=debug
```

--------------------------------

### Update License Documentation

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Run this command after adding or updating dependencies to regenerate license and dependency files.

```bash
make generate
```

--------------------------------

### Run Emissary-ingress Entrypoint

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Use this command to run the main entrypoint of Emissary-ingress locally. This requires the 'go' toolchain and will attempt to launch 'diagd' and 'envoy'.

```bash
go run ./cmd/busyambassador entrypoint
```

--------------------------------

### Get Emissary LoadBalancer IP Address (AWS)

Source: https://github.com/emissary-ingress/emissary/blob/main/charts/emissary-ingress/templates/NOTES.txt

For AWS, use this command to retrieve the LoadBalancer hostname. It may take a few minutes for the hostname to be available.

```bash
export SERVICE_IP=$(kubectl get svc --namespace {{ include "ambassador.namespace" .}} {{ include "ambassador.fullname" . }} -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
echo http://$SERVICE_IP:{{ .Values.service.port }}
```

--------------------------------

### Override Build Architecture

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Set the BUILD_ARCH environment variable to override the default build artifact architecture, for example, to build for Apple Silicon Macs.

```bash
BUILD_ARCH=linux/arm64 make images
```

--------------------------------

### Ambex Configuration Reload

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Shows how to edit configuration files in the ./example/ambex/ directory and trigger a reload. Use the --watch flag for instantaneous reloads or signal the process with 'killall -HUP ambex' for manual triggers.

```bash
killall -HUP ambex
```

--------------------------------

### Get Emissary NodePort IP Address

Source: https://github.com/emissary-ingress/emissary/blob/main/charts/emissary-ingress/templates/NOTES.txt

Use these commands when Emissary is exposed via a NodePort service. It retrieves the NodePort and the IP address of a node to construct the service URL.

```bash
export NODE_PORT=$(kubectl get --namespace {{ include "ambassador.namespace" .}} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "ambassador.fullname" . }})
export NODE_IP=$(kubectl get nodes --namespace {{ include "ambassador.namespace" .}} -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
```

--------------------------------

### Run Specific Go or Python Tests

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

To run specific Go tests, use `make gotest GOTEST_PKGS=./cmd/entrypoint GOTEST_ARGS="-run TestName"`. For specific Python tests, use `make pytest PYTEST_ARGS="-k TestName"`.

```bash
make gotest GOTEST_PKGS=./cmd/entrypoint GOTEST_ARGS="-run TestName"
```

```bash
make pytest PYTEST_ARGS="-k TestName"
```

--------------------------------

### Basic GNU Make Rule

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/gnu-make.md

Defines a target, its dependencies, and the command to execute when the target is out of date. Use this for simple build steps.

```makefile
target: dependency1 dependency2
	command to run
```

--------------------------------

### Clone Repository

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Clone your forked repository locally to begin making changes.

```shell
git clone <your-fork>
```

--------------------------------

### Prepare .Y Bump

Source: https://github.com/emissary-ingress/emissary/wiki/Starting-work-on-a-new-.Y-release

Run this script to create a commit, branches, and tags for a new .Y release. It will provide a git push command upon completion.

```bash
./releng/prepare-y-bump
```

--------------------------------

### Rebase Patch Branch on Base Branch

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Before starting work on a patch branch, ensure your local master is up-to-date and then rebase your patch branch onto master to maintain a linear commit history. This process may involve resolving merge conflicts.

```shell
# first, make sure you pull latest upstream changes
git fetch upstream
git checkout master
git pull -ff upstream/master

# checkout patch branch and rebase interactive
# you may have merge conflicts you need to resolve
git checkout my-patch-branch
git rebase -i master
```

--------------------------------

### Push Docker Images to Registry

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Retag and push the built Docker images to your configured container registry. Ensure Docker is logged in and has push permissions. You can also use `make env` or `make export` to view environment variables or get export-friendly output.

```bash
# re-tags the images and pushes them to your configured container registry
# docker must be able to login to your registry and you have to have push permissions
make push

# you can view the newly tag images by running
docker images | grep <your -registry>

# alternatively, we have two make targets that provide information as well
make env

# or in a bash export friendly format
make export
```

--------------------------------

### Build Envoy and Container Separately

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

A sequence of commands to build Envoy, then its container image, and finally test Emissary-ingress without pushing the container. Useful when not pushing intermediate images.

```shell
make build-envoy
make build-base-envoy-image
make test
```

--------------------------------

### Running Go Programs in Cleanup Rules

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/HACKING.md

When cleaning up Go programs, change to the program's source directory and use 'go run .'. This ensures the program is built and executed correctly within its own context.

```makefile
cd $(dir $(_myfile.mk))bin-go/PROGRAM && GO111MODULE=on go run . ARGS...
```

--------------------------------

### Standard .mk Snippet Header

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

All .mk snippets must begin with a header comment including a copyright statement, a brief description, and section headings for eager inputs, lazy inputs, outputs, and common.mk targets. Additional sections may be required for dependencies on other snippets.

```make
# Copyright statement.
#
# A sentence or two introducing what this file does.
#
## Section heading ##
#  - type: item
#  - type: item
## Section heading ##
#  - item
#  - item
#
# High-level prose documentation.

```

--------------------------------

### Deploy Emissary-ingress to Kubernetes

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Generate Helm charts and Kubernetes configurations with your container image swapped in, and apply them to your cluster. Verify the deployment by checking the Emissary pod status in the `ambassador` namespace.

```bash
# generate helm charts and K8's Configs with your container swapped in and apply them to your cluster
make deploy

# check your cluster to see if emissary is running
# note: kubectl doesn't know about  DEV_KUBECONFIG so you may need to ensure KUBECONFIG is pointing to the correct cluster
kubectl get pod -n ambassador
```

--------------------------------

### Load Ambassador Configuration Resources

Source: https://github.com/emissary-ingress/emissary/blob/main/python/README.md

Instantiate an `ambassador.Config` object and load a list of `ACResource` objects into it. This method should only be called once with all resources.

```python
aconf: Config = Config()
aconf.load_all(resources: List[ACResource])
```

--------------------------------

### Clean Build Environment

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Use `make clobber` to remove all derived objects and cached artifacts for a clean build. Use `make clean` to remove derived objects but preserve caches.

```bash
make clobber
```

```bash
make clean
```

--------------------------------

### Variable Input/Output Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Use 'Variable' to denote variables. For inputs, include '?= value' if a default value exists. For outputs, include '= value' or '?= value' to document the variable's content, indicating if it can be overridden.

```make
Variable
```

--------------------------------

### Run All Emissary-ingress Tests

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Execute `make test` to run all tests. Use `make gotest` for all Go tests and `make pytest` for all Python tests.

```bash
make test
```

```bash
make gotest
```

```bash
make pytest
```

--------------------------------

### Target Output Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Use 'Target(s)' to indicate that the snippet defines rules to create specified file(s). List each target separately, or use the plural 'Targets' for expressions covering a wide range of files.

```make
Target(s)
```

--------------------------------

### Initialize and Branch Envoy Sources

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Fetch the current Envoy sources vendored with Emissary-ingress and create a new branch for modifications. This command should be run from your `emissary.git` checkout.

```shell
make $PWD/_cxx/envoy
git -C _cxx/envoy checkout -b YOUR_BRANCHNAME
```

--------------------------------

### List Kubernetes Resource Statuses

Source: https://github.com/emissary-ingress/emissary/blob/main/cmd/kubestatus/README.md

Use this command to list the statuses of Kubernetes resources matching the specified kind and selectors. No updates are made by default.

```bash
kubestatus service -f metadata.name=foo
```

--------------------------------

### Build Base Envoy Docker Image

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Generates a new 'base-envoy' container image using the release outputs from building Envoy binaries.

```shell
make build-base-envoy-image
```

--------------------------------

### Build Envoy Binaries

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Builds the Envoy binaries using the upstream Envoy project's build container. Outputs are placed in '_cxx/envoy-docker-build'.

```shell
make build-envoy
```

--------------------------------

### Outputs Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Outputs section lists targets, variables, etc. that the snippet defines. This includes rules to create files, .PHONY targets, variables, functions, and executables.

```make
## Outputs ##
```

--------------------------------

### Build Docker Images

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Build the necessary Docker containers for Emissary-ingress, including the main Emissary container and test client/server containers. This command may take time on the first run as base images are built and cached.

```bash
# This will pull and build the necessary docker containers and produce multiple containers.
# If this is the first time running this command it will take a little bit while the base images are built up and cached.
make images

# verify containers were successfully created, you should also see some of the intermediate builder containers as well
docker images | grep emissary.local
```

--------------------------------

### Create and Push GA Git Tags

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(2.3.z)

Use these commands to create and push annotated Git tags for a general availability (GA) Emissary release and its Helm chart. Update the version variables to reflect the GA versions.

```shell
version=2.2.0
chart_version=7.3.0
git tag --annotate --message="Emissary ${version} GA release" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} GA release for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

--------------------------------

### Deploy Development Container

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Run this command to recompile, rebuild, push, and re-deploy Emissary-ingress to your cluster for live testing.

```shell
make deploy
```

--------------------------------

### Adding targets to 'make help'

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/intro.md

Add custom targets to the 'make help' output by using a magic comment '##' followed by a description. This makes your custom targets visible in the help information.

```makefile
frob: ## Frobnicate the splorks
```

--------------------------------

### Create and Push RC Git Tags

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(2.3.z)

Use these commands to create and push annotated Git tags for an Emissary release candidate and its corresponding Helm chart. Ensure the version variables are set correctly.

```shell
version=2.2.0-rc.3
chart_version=7.3.0-rc.3
git tag --annotate --message="Emissary ${version} release candidate" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} release candidate for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

--------------------------------

### Create and Push Emissary and Chart Git Tags

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(2.3.z)

Use this command to create and push both the Emissary version tag and its corresponding Helm chart tag simultaneously. It's crucial that both tags are pushed together to ensure CI processes function correctly.

```shell
version=2.2.0-rc.3
chart_version=7.3.0-rc.3
git tag --annotate --message="Emissary ${version} release" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} release for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

--------------------------------

### Redeploy Emissary with Local Images

Source: https://github.com/emissary-ingress/emissary/blob/main/test/e2e/README.md

Build Emissary images and install/upgrade the charts, useful when code changes require redeployment without cluster recreation. Explicitly set the VERSION to avoid Kubernetes label limits.

```bash
make images && make VERSION=v4.0.0-local e2e/install
```

--------------------------------

### Run Envoy Test Suite

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Executes the Envoy test suite within the build Docker container against the Envoy code in the '_cxx/envoy' folder.

```shell
make check-envoy
```

--------------------------------

### Test with Private Docker Repository

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Configure these environment variables to enable the test machinery to create an imagePullSecret for pulling images from a private Docker repository.

```bash
export DEV_USE_IMAGEPULLSECRET=true
export DOCKER_BUILD_USERNAME=...
export DOCKER_BUILD_PASSWORD=...
```

--------------------------------

### Configure Development Environment Variables

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Set the `DEV_REGISTRY` and `DEV_KUBECONFIG` environment variables to specify your container registry and development Kubernetes configuration file. Ensure you are logged into your registry and have push permissions.

```bash
# set container registry using `export DEV_REGISTRY=<your-registry>
# note: you need to be logged in and have permissions to push
# Example:
export DEV_REGISTRY=docker.io/parsec86

# set kube config file using `export DEV_KUBECONFIG=<dev-kubeconfig>`
# your cluster needs the ability to read from the configured container registry
export DEV_KUBECONFIG="$HOME/.kube/dev-config.yaml"
```

--------------------------------

### Create GA Git Tags for Emissary and Chart

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(3.y.z)

Execute these commands to create and push annotated Git tags for the General Availability (GA) release of Emissary and its Helm chart. Update the version variables to reflect the GA versions.

```shell
version=3.1.0
chart_version=8.1.0
git tag --annotate --message="Emissary ${version} GA release" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} GA release for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

--------------------------------

### Run Ambex CLI with busyambassador

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

This command demonstrates how to run the ambex CLI using the busyambassador tool. Replace ARGs with any necessary arguments for ambex.

```shell
go run github.com/datawire/ambassador/cmd/busyambassador ambex ARGs...
```

--------------------------------

### Activate Python Virtual Environment

Source: https://github.com/emissary-ingress/emissary/blob/main/test/e2e/README.md

Activate the Python virtual environment to ensure correct resolution of project dependencies for Makefile invocations.

```bash
source .venv/bin/activate     # or: uv run make ...
```

--------------------------------

### Executable Output Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Use 'Executable' for outputs that are variables storing absolute paths to executables. These can be overridden by environment variables and have associated rules for creation if they don't exist.

```make
Executable
```

--------------------------------

### Explain Kubernetes Resource Status Schema

Source: https://github.com/emissary-ingress/emissary/blob/main/cmd/kubestatus/README.md

Use kubectl explain to understand the expected JSON schema for the status field of a Kubernetes resource. This is useful for formatting the status update file.

```bash
kubectl explain service.status
```

```bash
kubectl explain service.status.loadBalancer
```

--------------------------------

### Create RC Git Tags for Emissary and Chart

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(3.y.z)

Use these commands to create and push annotated Git tags for both the Emissary release candidate and its Helm chart. Ensure the version variables are set correctly.

```shell
version=3.1.0-rc.0
chart_version=8.1.0-rc.0
git tag --annotate --message="Emissary ${version} release candidate" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} release candidate for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

--------------------------------

### Tidy Go Modules

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Run `make go-mod-tidy` to ensure your `go.mod` and `go.sum` files are consistent and tidy. Commit any changes generated by this command.

```bash
make go-mod-tidy
```

--------------------------------

### File Input Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Use 'File' to indicate that a file is parsed by the Makefile snippet. This input should not be described by a Target, as it needs to exist at Makefile-parse-time.

```make
File
```

--------------------------------

### Create Patch Branch

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Create a new branch from 'master' to isolate your changes.

```shell
git checkout master
git checkout -b my-patch-branch master
```

--------------------------------

### Force Push with Lease

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Force pushes your local branch to the remote repository, using `--force-with-lease` for safety. This is necessary after a rebase.

```shell
git push head --force-with-lease
```

--------------------------------

### Makefile Rule for TAP Test Runner

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/testing.md

Defines a Makefile rule to run a custom test command, pipe its TAP output to `tee` for saving to a .tap file, and then stream it for pretty-printing.

```makefile
my-test.tap: my-test.input $(tools/tap-driver) FORCE
	@SOME_COMMAND_THAT_EMITS_TAP 2>&1 | tee $@ | $(tools/tap-driver) stream -n my-test
```

--------------------------------

### Create and Push Release Tags

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(3.y.z)

Use this command to create and push annotated Git tags for both the Emissary project and its Helm chart. Ensure both tags are pushed in a single command to maintain CI integrity.

```shell
version=3.1.0-rc.0
chart_version=8.1.0-rc.0
git tag --annotate --message="Emissary ${version} release" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} release for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

--------------------------------

### Update Base Envoy Container and Test

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Builds a new base Envoy container and pushes it, then runs the Emissary-ingress test suite. This is the recommended workflow when Envoy changes are involved.

```shell
make update-base
make test
```

--------------------------------

### Extending 'make build' target

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/intro.md

Extend the 'make build' target to include custom build steps, such as building a specific file.

```makefile
build: foo
```