Skip to content

Latest commit

 

History

History
194 lines (134 loc) · 6.13 KB

contributing.md

File metadata and controls

194 lines (134 loc) · 6.13 KB
Raw

How to Contribute to Nuclio

This guide will guide you through the process of setting up a development environment and contributing to Nuclio.

In This Document

Prerequisites

Ensure that your setup includes the following prerequisite components:

  • Linux or OSX
  • Git
  • Docker version 19.03+
  • The Go toolchain (CI tests with 1.21, best use that)
  • Kubernetes version 1.24+ (mostly for testing) - minikube recommended; (you can follow the Minikube getting-started guide)

Getting the source code

Fork the Nuclio GitHub repository and clone it:

git clone https://github.com/<your username>/nuclio.git ~/nuclio

Check out the development branch, because that's where all the goodness happens:

cd ~/nuclio && git checkout development

Now, use make modules to get Nuclio's dependencies and modules

Build Nuclio artifacts (nuctl, container images):

make build

You should now have quite a few nuclio/<something> images tagged as latest-amd64, along with nuctl-latest-<os>-amd64 with a nuctl symbolic link under $GOPATH/bin.

Note: to make nuclio container images available for arm64 architecture run NUCLIO_ARCH=arm64 make build

Now, run a few unit tests:

make lint test-unit

This is a short test suite, and requires only Docker.

Note: Writing (Go) Nuclio tests requiring it having build tag annotation at the first line Use the following build tag annotations to match the test purpose:

  • test_unit - unit testings
  • test_integration - integration testings
  • test_functional - functional testings
  • test_kube - requires kubernetes platform
  • test_local - requires docker platform
  • test_iguazio - requires Iguazio system
  • test_broken - test suite is broken, cannot be executed on CI

To run Kubernetes nuctl suite locally:

NUCTL_REGISTRY=<registry> make test-k8s-nuctl

To run Docker nuctl suite locally:

make test-docker-nuctl

To run Kubernetes platform integration test locally:

# Installing nuclio CRDs
$ sh test/k8s/ci_assets/install_nuclio_crds.sh

# Running local Docker registry
$ docker run --rm -d -p 5000:5000 registry:2

$ make test-k8s

To run integration tests for docker platform, run:

make test

Note: it may take a while ~90 minutes

On Nuclio CI, we run nuctl test suites against both Docker and Kubernetes platforms.

Running more comprehensive end-to-end tests on kubernetes is currently done manually.

When you're done, create a feature branch from the development branch; (Nuclio follows the GitFlow branching model):

git checkout -b my-feature

Setting up a GoLand project

The Nuclio team is a fan of GoLand and uses it heavily for Go projects. It was decided not to include the .idea files at this time, but it's very easy to create run/debug targets and use the debugger

  1. Clone nuclio git clone [email protected]:nuclio/nuclio.git > ~/nuclio
  2. Open GoLand and File > Open and select ~/nuclio
  3. Enable go modules **GoLand > Preferences > Go > Ensure Enable Go Modules box is checked
  4. Run configurations are (currently) available for tests only

For developing in nuclio locally, see Local development.

Versioning note

All Nuclio artifacts are versioned. They take their versions from variables in v3io/version-go/version.go.

During link time, the linker set the version variables using the -X flag.

Since there is an auto-fallback to "latest", if you want to use versioned binaries, make sure to pass the following as part of the Go tool arguments in the Run/Debug configuration:

-ldflags="-X github.com/v3io/version-go.label=1.7.2"

Running the processor (Go)

Under normal circumstances, the function provided by the user is compiled as a Go plugin that's loaded by the processor. If you need to debug this plugin loading mechanism, you're advanced enough to find your way around. If all you want to do is test a new feature on the processor, the easiest way to achieve this is to use Go with the built-in handler (nuclio:builtin). When you specify handler: nuclio:builtin in the processor configuration file, the Go runtime doesn't try to load a plugin and simply uses pkg/processor/runtime/golang/runtime.go:builtInHandler(). Feel free to modify that function, just don't check in your changes.

The processor configuration file is basically the content of your function.yaml function-configuration file:

spec:
  runtime: golang
  handler: nuclio:builtin
  logger:
    level: debug
  triggers: { }

Another configuration that should be given to the processor is the platform configuration, which looks like this:

logger:
  sinks:
    myStdoutLoggerSink:
      kind: stdout
  system:
    - level: debug
      sink: myStdoutLoggerSink
  functions:
    - level: debug
      sink: myStdoutLoggerSink

Create these two configuration files in your preferred location, and pass --config <path to processor.yaml> --platform-config <path to platform-config.yaml as Program arguments in the Run/Debug configuration.

For more information about the platform configuration, see Configuring a Platform. For information about the function configuration, see the Function-Configuration Reference.

Running the Nuclio CLI (nuctl)

There's nothing special required to run nuctl, but you may want to pass --platform local in case you don't want to work with Kubernetes.

Submitting a PR

Your PRs will go through GitHub Action CI and code review. Make sure to follow the coding conventions and run make fmt lint before submitting a PR, that would save you some time failing on CI linting and test validations