Skip to content

Latest commit

 

History

History
90 lines (65 loc) · 4.05 KB

contributing.md

File metadata and controls

90 lines (65 loc) · 4.05 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.

Set up some prerequisites

Obviously, you'll need:

  • Linux or OSX
  • git
  • Docker (version 17.05+, because Nuclio uses multi-stage builds)
  • The Go toolchain (CI tests with 1.9, best use that)
  • A GOPATH directory and GOPATH environment variable set to that
  • Kubernetes 1.7+ (for testing, mostly) - minikube recommended (you can follow the minikube getting started guide)

Getting the source

Fork Nuclio and clone it:

git clone https://github.com/<your username>/nuclio.git $GOPATH/src/github.com/nuclio/nuclio

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

cd $GOPATH/src/github.com/nuclio/nuclio && git checkout development

Now go get some dependencies that are injected into functions and cannot be vendored:

go get github.com/v3io/v3io-go-http/... && go get github.com/nuclio/logger/... && go get github.com/nuclio/nuclio-sdk-go/... && go get github.com/nuclio/amqp/...

Build Nuclio artifacts (nuctl, Docker images):

make build

You should now have quite a few nuclio/<something> images tagged as latest-amd64 along with nuctl-latest-<os>-amd64, symlinked as nuctl under $GOPATH/bin. Let's run a few tests:

make lint test

This may take a while (about 10 minutes) and only needs docker. End to end testing on Kubernetes is still done manually. Create a feature branch from development (Nuclio follows gitflow):

git checkout -b my-feature

Setting up a GoLand project

We <3 GoLand and use it heavily for Go projects. We chose not to include the .idea files at this time, but it is super easy to create run/debug targets and use the debugger:

  1. Create a new project pointing to $GOPATH/src/github.com/nuclio/nuclio
  2. Click "GoLand-EAP" -> Preferences -> Go -> GOPATH and add the value of $GOPATH

A note about versioning

All Nuclio artifacts are versioned. They take their versions from one of two sources (in the following order):

  1. Variables in pkg/version/version.go, set by the linker during link time using -X
  2. A version file, residing at /etc/nuclio/version_info.json

As of now, there is no auto-fallback to "latest" to prevent un-versioned binaries ever getting created. As such, make sure to pass the following to Go tool arguments in the Run/Debug configuration:

-i -ldflags="-X github.com/nuclio/nuclio/pkg/version.label=latest -X github.com/nuclio/nuclio/pkg/version.arch=amd64"

Running the processor (Go)

Under normal circumstances, the function provided by the user will be compiled as a Go plugin 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 go about this is to use Go with the "built in" handler.

By specifying handler: nuclio:builtin in the processor configuration file, the Go runtime will not try to load a plugin and simply use pkg/processor/runtime/golang/runtime.go:builtInHandler(). Feel free to modify that function, just don't check it in.

The processor configuration file currently has this schema (in the future it will be changed to the schema of function.yaml):

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

Create this file somewhere and pass --config <path to processor.yaml> as Program arguments in the Run/Debug configuration.

Running 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 travis CI and code review. Make sure to follow the coding conventions and run make lint test before submitting to make sure you haven't broken anything.