botkube/CONTRIBUTING.md

How to Contribute to BotKube

We'd love your help!

BotKube is MIT Licensed and accepts contributions via GitHub pull requests. This document outlines some of the conventions on development workflow, commit message formatting, contact points and other resources to make it easier to get your contributions accepted.

We gratefully welcome improvements to documentation as well as to code.

Contributing to documentation

You can contribute to documentation by following these instructions

Compile BotKube from source code

Before you proceed, make sure you have installed BotKube Slack/Mattermost/Teams app and copied the required token as per the steps documented here

Prerequisite

• Make sure you have go 1.11+ installed with go module activated. (You can set env var with export GO111MODULE=on to activate)

• You will also need make and docker installed on your machine.

• Clone the source code

  $ git clone https://github.com/infracloudio/botkube.git
  

Now you can build and run BotKube by one of the following ways

Build the container image

1. This will build BotKube and create a new container image tagged as infracloudio/botkube:latest

   $ make build
   $ make container-image
   $ docker tag infracloudio/botkube:latest-amd64 <your_account>/botkube:latest
   $ docker push <your_account>/botkube:latest
   

   Where <your_account> is Docker hub account to which you can push the image

2. Deploy newly created image in your cluster.

   a. Using helm (v3)

   $ helm repo add infracloudio https://infracloudio.github.io/charts
   $ helm repo update
   $ kubectl create namespace botkube
   $ helm install --version v9.99.9-dev botkube --namespace botkube \
     --set communications.slack.enabled=true \
     --set communications.slack.channel=<SLACK_CHANNEL_NAME> \
     --set communications.slack.token=<SLACK_API_TOKEN_FOR_THE_BOT> \
     --set settings.clustername=<CLUSTER_NAME> \
     --set settings.kubectl.enabled=<ALLOW_KUBECTL> \
     --set image.repository=<your_account>/botkube \
     --set image.tag=latest \
     infracloudio/botkube
   

   Check values.yaml for default options

   Note:

   If you are using helm version < 3.0.0, use following command

   helm install --version v9.99.9-dev --name botkube --namespace botkube --set <options> infracloudio/botkube

   b. Using kubectl

   1. Edit deploy-all-in-one.yaml and update the configuration. Set SLACK_ENABLED, SLACK_CHANNEL, SLACK_API_TOKEN, clustername, kubectl.enabled and update the resource events configuration you want to receive notifications for in the configmap.
   2. Create botkube namespace and deploy resources

   $ kubectl create ns botkube && kubectl create -f deploy-all-in-one.yaml -n botkube
   

Build and run BotKube locally

For faster development, you can also build and run BotKube outside K8s cluster.

1. Build BotKube binary if you don't want to build the container image, you can build the binary like this,

   # Fetch the dependencies
   $ go mod download
   # Build the binary
   $ go build ./cmd/botkube/
   

2. Edit ./resource_config.yaml and ./comm_config.yaml to configure resource and set communication credentials.

3. Export the path to directory of config.yaml

   # From project root directory
   $ export CONFIG_PATH=$(pwd)
   

4. Make sure that correct context is set and you are able to access your Kubernetes cluster

   $ kubectl config current-context
   minikube
   $ kubectl cluster-info
   Kubernetes master is running at https://192.168.39.233:8443
   CoreDNS is running at https://192.168.39.233:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
   ...
   

5. Run BotKube binary

   $ ./botkube
   

Making A Change

• Before making any significant changes, please open an issue. Discussing your proposed changes ahead of time will make the contribution process smooth for everyone.

• Once we've discussed your changes and you've got your code ready, make sure that the build steps mentioned above pass. Open your pull request against develop branch.

• To avoid build failures in CI, run

  # From project root directory
  $ ./hack/verify-*.sh
  

  This will check if the code is properly formatted, linted & vendor directory is present.

• Run e2e tests

  $ ./hack/runtests.sh
  

• Make sure your pull request has good commit messages:

  • Separate subject from body with a blank line
  • Limit the subject line to 50 characters
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Use the imperative mood in the subject line
  • Wrap the body at 72 characters
  • Use the body to explain what and why instead of how

• Try to squash unimportant commits and rebase your changes on to develop branch, this will make sure we have clean log of changes.