Skip to content
This repository has been archived by the owner on Dec 11, 2023. It is now read-only.

Latest commit

 

History

History
311 lines (219 loc) · 11.4 KB

contributing.md

File metadata and controls

311 lines (219 loc) · 11.4 KB
Raw

Contributing to TriggerMesh

Welcome, contributors! 👋

Thank you for taking the time to go through this document, which suggests a few guidelines for contributing to the TriggerMesh open source platform.

We define contributions as:

  • Bug reports
  • Feature and enhancement requests
  • Code submissions
  • Any participation in discussions within the TriggerMesh community

Contents

Code of Conduct

Although this project is not part of the CNCF, we abide by its Code of Conduct, and expect all contributors to uphold this code. Please report unacceptable behavior to [email protected].

Submitting Contributions

The guidelines below aim at ensuring that maintainers can understand submissions as quickly and effortlessly as possible, whether these are questions, issue reports, feature requests, or code contributions. The golden rule is: the clearer the information, the faster the resolution 🚀.

Reporting Bugs

Bugs, or any kind of issue you encounter with the TriggerMesh platform, can be reported using GitHub Issues.

Before opening a new issue, kindly search for a few keywords related to the problem you encountered, just to ensure a similar report hasn't already been submitted. Didn't find anything relevant? Great! 👍 Let's create that issue.

ℹ️ If you suspect or discover a security vulnerability in the TriggerMesh software, please do not disclose it publicly via a GitHub issue. Instead, please report it to [email protected] so that maintainers can address it within the shortest possible delay. 🔒⌛

Issue Description

A good bug report starts with a clear and descriptive title. Avoid overly generic titles such as "bug in component X", or raw outputs from error logs. Indicate what is failing and, if known, under what circumstances it is failing (e.g. "Component X panics when environment variable Y is not set").

Although there is no enforced template for submitting issues, we do recommend including the following information:

  • A detailed description, in plain English, of the behaviour you are observing, and what you expected instead.
  • The release version of Scoby the problem can be observed with (or software revision if the software was built from source).
  • The component that is affected (registration, rendering, hook, etc.)
  • A configuration snippet that can be used to reproduce the issue.
  • If some preliminary setup of a third-party service was performed, please describe those steps.
  • The error messages you are seeing, if any.
    • 💡 Most errors are reported via Kubernetes API events and object statuses. Both can be obtained using the kubectl describe command.

Remember, anything that allows maintainers to reproduce the problem from the initial issue description is another day saved going back and forth to the issue's comments to ask for additional information, leading to your issue being solved faster! 🙌

Code Styling

To ensure the indentation of command outputs and the highlighting of code snippets are preserved inside the text of GitHub issues, we recommend wrapping them inside Fenced Code Blocks using the triple backticks notation (```).

Examples:

Raw Markdown Rendered code block 
```
[2021/12/01 15:43:04] Some log output
```

[2021/12/01 15:43:04] Some log output

```yaml
# My Kubernetes manifest
apiVersion: triggermesh.io/v1
```

# My Kubernetes manifest
apiVersion: triggermesh.io/v1

Requesting Features and Enhancements

Features and enhancements can be reported using GitHub Issues.

Similarly to bug reports, we kindly ask you to search for a few keywords related to your suggestion before opening a new issue, just to ensure a similar request hasn't already been submitted. In case that search doesn't yield any relevant result, let's go ahead and create that issue. 📝

Provide a detailed description, in plain English, of the result you are expecting by submitting your request:

  • If you are asking for an enhancement to an existing component, be specific about which component. If possible, include links to any external resources that may help maintainers get a clearer understanding of the desired outcome.
  • If you are asking for a new feature, please clarify the nature of that feature. Examples include:
    • A new integration with a third-party service.
    • A new data processor.
    • A new authentication method.
    • ...

The clearer the request, the easier it is for maintainer to discuss a potential design and implementation! :raised_hands:

Submitting Code Changes

Code submissions can be proposed using GitHub Pull Requests.

Whenever a pull request is opened, and every time it is updated by pushing new commits, the CI pipeline performs some static code analysis on the submitted code revision to ensure that certain code styles are respected. All status checks must be passing for a pull request to be considered by maintainers. ✔️

Small, non-breaking changes, can be submitted spontaneously without prior discussion with maintainers, providing that they include a clear justification of their potential relevance to the project.

Larger changes such as new features, or changes which impact the current behaviour of certain TriggerMesh components, should be socialized and discussed with maintainers in a GitHub Issue. Nobody likes seeing a submission getting rejected because it was not aligned with the project's goals or standards! 😞

If you read that far and are feeling ready to submit your first code contribution, congratulations! ❤️ Read on, the following section about Development Guidelines explains what our standard development environment looks like.

Development Guidelines

Prerequisites

  • Go toolchain
  • Kubernetes
  • ko

Go Toolchain

TriggerMesh is written in Go.

The Go toolchain is required in order to be able to compile the TriggerMesh code and run its automated tests.

The currently recommended version can be found inside the go.mod file, based on the go directive.

Kubernetes

TriggerMesh runs on top of the Kubernetes platform.

Any certified Kubernetes distribution can run TriggerMesh, whether it is running locally (e.g. using kind, inside a virtual machine, ...) or remotely (e.g. inside a cloud provider, in your own datacenter, ...).

The currently recommended version can be found inside the go.mod file, based on the version of the k8s.io/api module dependency.

ko

ko is a tool which allows developers to package Go projects as container images and deploy them to Kubernetes in a single command, all of this without requiring Docker to be installed.

TriggerMesh relies on ko extensively, both for development purposes and for its own releases.

We recommend using version v0.9.0 or greater.

Running the Controller

Controller Configuration

The Scoby controller uses controller-runtime and follows its configuration approach.

Running Locally

It is possible to run the TriggerMesh controller (cmd/scoby-controller/main.go) locally, and let it operate against any Kubernetes cluster, whether this cluster is running locally (e.g. inside a virtual machine) or remotely (e.g. inside a cloud provider).

⚠️ Before running the controller in your local environment, make sure no other instance of the TriggerMesh controller is currently running inside the target cluster! This could prevent your local instance from performing any work due to the leader-election mechanism, or worse, result in multiple controllers performing conflicting changes simultaneously to the same objects.

Providing that (1) the local environment is configured with a valid [kubeconfig][k8s-kubecfg] and (2) the aforementioned mandatory environment variables are exported, running the controller locally from the current development branch is as simple as executing:

To setup a development environment you need to create the CRDRegistration object first, then run the controller:

# Apply registration
kubectl apply -f config/300-crdregistration.yaml

# Run controller
go run cmd/scoby-controller/main.go --zap-log-level 5

Running With KO

Development version can be installed at the configured cluster using ko

ko apply -f ./config

License Headers

License headers must be written using SPDX identifier.

// Copyright 2023 TriggerMesh Inc.
// SPDX-License-Identifier: Apache-2.0

Use addlicense to automatically add the header to all go files.

addlicense -c "TriggerMesh Inc." -y $(date +"%Y") -l apache -s=only ./**/*.go

Logs

The controller rely on controller-runtime which uses the logr wrapper over zap logger.

  • To enable development configuration use --zap-devel.
  • Verbosity can be controlled by using --zap-log-level <level>.

Verbosity

Scoby uses logr to write logs. When debugging we will use verbosity levels 0,1,5,10 in this way:

V Description
0 Always shown, equals to info level
1 Equals to debug level
2 - 5 Use levels 2 - 5 for chatty debug logs
6 - 10 Use leves for spammy debug logs (eg. inside loops)