From 015bd65ebcd8a3888bc41170219d00a68100e296 Mon Sep 17 00:00:00 2001 From: Christie Wilson Date: Sat, 22 Jun 2019 16:54:42 -0700 Subject: [PATCH] =?UTF-8?q?Add=20initial=20docs=20=F0=9F=93=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Most of these docs have been copy pasted from https://github.com/tektoncd/pipelines. These docs currently refer to code and config that doesn't yet exist, but point us the direction of a great first step, which would be to make it so that the info in these docs is correct (e.g. we can build and deploy a controller, even if it doesn't do anything, etc.). These are the docs required at https://github.com/tektoncd/community/blob/master/process.md#project-requirements --- .github/issue-template.md | 16 ++ .github/pull_request_template.md | 29 ++++ CONTRIBUTING.md | 48 ++++++ DEVELOPMENT.md | 273 +++++++++++++++++++++++++++++++ code-of-conduct.md | 75 +++++++++ test/README.md | 4 + 6 files changed, 445 insertions(+) create mode 100644 .github/issue-template.md create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 DEVELOPMENT.md create mode 100644 code-of-conduct.md create mode 100644 test/README.md diff --git a/.github/issue-template.md b/.github/issue-template.md new file mode 100644 index 000000000..e9044a11b --- /dev/null +++ b/.github/issue-template.md @@ -0,0 +1,16 @@ +--- +name: Issue Template +about: Template for both bug reports and feature requests +--- + +# Expected Behavior + +# Actual Behavior + +# Steps to Reproduce the Problem + +1. +2. +3. + +# Additional Info diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..8d64aa896 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,29 @@ +# Changes + + + + + +# Submitter Checklist + +These are the criteria that every PR should meet, please check them off as you +review them: + +- [ ] Includes [tests](https://github.com/tektoncd/community/blob/master/standards.md#principles) (if functionality changed/added) +- [ ] Includes [docs](https://github.com/tektoncd/community/blob/master/standards.md#principles) (if user facing) +- [ ] Commit messages follow [commit message best practices](https://github.com/tektoncd/community/blob/master/standards.md#commit-messages) + +_See [the contribution guide](https://github.com/tektoncd/triggers/blob/master/CONTRIBUTING.md) for more details._ + +# Release Notes + +``` +Describe any user facing changes here, or delete this block. + +Examples of user facing changes: +- API changes +- Bug fixes +- Any changes in behavior + +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..83759e1eb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to Tekton Triggers + +Welcome to the Tekton Triggers project! Thanks for considering contributing to +our project and we hope you'll enjoy it :D + +**All contributors must comply with +[the code of conduct](./code-of-conduct.md).** + +To get started developing, see our [DEVELOPMENT.md](./DEVELOPMENT.md). + +In [the community repo](https://github.com/tektoncd/community) you'll find info +on: + +- [Contacting other contributors](https://github.com/tektoncd/community/blob/master/contact.md) +- [Development standards](https://github.com/tektoncd/community/blob/master/standards.md) + around + [principles](https://github.com/tektoncd/community/blob/master/standards.md#principles), + [commit messages](https://github.com/tektoncd/community/blob/master/standards.md#commit-messages) + and + [code](https://github.com/tektoncd/community/blob/master/standards.md#coding-standards) +- [Processes](https://github.com/tektoncd/community/blob/master/process.md) like + [finding something to work on](https://github.com/tektoncd/community/blob/master/process.md#finding-something-to-work-on), + [proposing features](https://github.com/tektoncd/community/blob/master/process.md#proposing-features), + [reviews](https://github.com/tektoncd/community/blob/master/process.md#reviews) + and + [becoming an OWNER](https://github.com/tektoncd/community/blob/master/process.md#owners) + +You can find details on our automation infrastructure in +[the plumbing repo](https://github.com/tektoncd/plumbing). + +For more Triggers specific guidelines, see: + +- [The Tekton Triggers ZenHub project](#zenhub-project) + +See also [the Tekton Pipelines roadmap](http://github.com/tektoncd/pipeline/blob/master/roadmap-2019.md) + +## ZenHub project + +You can see project details (including a burndown, issues in epics, etc.) on +[our ZenHub board](https://app.zenhub.com/workspaces/triggers-5d0ebce343e42a09a0a4a826). + +To see this board, you must: + +- Ask [an OWNER](OWNERS) via + [slack](https://github.com/tektoncd/community/blob/master/contact.md#slack) + for an invitation +- Add [the ZenHub browser extension](https://www.zenhub.com/extension) to see + new info via GitHub (or just use zenhub.com directly) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..4c8aef1a0 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,273 @@ +# Tekton Triggers Development Guide + +## Getting started + +1. [Ramp up on kubernetes and CRDs](#ramp-up-on-crds) +1. [Ramp Tekton Pipelines](#ramp-up-on-tekton-pipelines) +1. Create [a GitHub account](https://github.com/join) +1. Setup + [GitHub access via SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) +1. [Create and checkout a repo fork](#checkout-your-fork) +1. Set up your [shell environment](#environment-setup) +1. Install [requirements](#requirements) +1. [Set up a Kubernetes cluster](#kubernetes-cluster) +1. [Configure kubectl to use your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) +1. [Set up a docker repository you can push to](https://github.com/knative/serving/blob/master/docs/setting-up-a-docker-registry.md) +1. [Install Tekton Pipelines](#install-pipelines) +1. [Install Tekton Triggers](#install-triggers) +1. [Iterate!](#iterating) + +### Ramp up + +Welcome to the project!! You may find these resources helpful to ramp up on some +of the technology this project is built on. + +#### Ramp up on CRDs + +This project extends Kubernetes (aka +`k8s`) with Custom Resource Definitions (CRDSs). To find out more: + +- [The Kubernetes docs on Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) - + These will orient you on what words like "Resource" and "Controller" + concretely mean +- [Understanding Kubernetes objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/) - + This will further solidify k8s nomenclature +- [API conventions - Types(kinds)](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds) - + Another useful set of words describing words. "Objects" and "Lists" in k8s + land +- [Extend the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/)- + A tutorial demonstrating how a Custom Resource Definition can be added to + Kubernetes without anything actually "happening" beyond being able to list + Objects of that kind + +#### Ramp up on Tekton Pipelines + +- [Tekton Pipelines README](https://github.com/tektoncd/pipeline/blob/master/docs/README.md) - + Some of the terms here may make more sense! +- Install via + [official installation docs](https://github.com/tektoncd/pipeline/blob/master/docs/install.md) + or continue though [getting started for development](#getting-started) +- [Tekton Pipeline "Hello World" tutorial](https://github.com/tektoncd/pipeline/blob/master/docs/tutorial.md) - + Define `Tasks`, `Pipelines`, and `PipelineResources`, see what happens when + they are run + +### Checkout your fork + +The Go tools require that you clone the repository to the +`src/github.com/tektoncd/triggers` directory in your +[`GOPATH`](https://github.com/golang/go/wiki/SettingGOPATH). + +To check out this repository: + +1. Create your own + [fork of this repo](https://help.github.com/articles/fork-a-repo/) +1. Clone it to your machine: + +```shell +mkdir -p ${GOPATH}/src/github.com/tektoncd +cd ${GOPATH}/src/github.com/tektoncd +git clone git@github.com:${YOUR_GITHUB_USERNAME}/triggers.git +cd triggers +git remote add upstream git@github.com:tektoncd/triggers.git +git remote set-url --push upstream no_push +``` + +_Adding the `upstream` remote sets you up nicely for regularly +[syncing your fork](https://help.github.com/articles/syncing-a-fork/)._ + +### Requirements + +You must install these tools: + +1. [`go`](https://golang.org/doc/install): The language Tekton Pipelines is + built in +1. [`git`](https://help.github.com/articles/set-up-git/): For source control +1. [`dep`](https://github.com/golang/dep): For managing external Go + dependencies. - Please Install dep v0.5.0 or greater. +1. [`ko`](https://github.com/google/ko): For development. `ko` version v0.1 or + higher is required for `triggers` to work correctly. +1. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For + interacting with your kube cluster + +Your [`$GOPATH`] setting is critical for `ko apply` to function properly: a +successful run will typically involve building pushing images instead of only +configuring Kubernetes resources. + +## Kubernetes cluster + +Docker for Desktop using an edge version has been proven to work for both +developing and running Pipelines. The recommended configuration is: + +- Kubernetes version 1.11 or later +- 4 vCPU nodes (`n1-standard-4`) +- Node autoscaling, up to 3 nodes +- API scopes for cloud-platform + +To setup a cluster with GKE: + +1. [Install required tools and setup GCP project](https://github.com/knative/docs/blob/master/docs/install/Knative-with-GKE.md#before-you-begin) + (You may find it useful to save the ID of the project in an environment + variable (e.g. `PROJECT_ID`). + +1. Create a GKE cluster (with `--cluster-version=latest` but you can use any + version 1.11 or later): + + ```bash + export PROJECT_ID=my-gcp-project + export CLUSTER_NAME=mycoolcluster + + gcloud container clusters create $CLUSTER_NAME \ + --enable-autoscaling \ + --min-nodes=1 \ + --max-nodes=3 \ + --scopes=cloud-platform \ + --enable-basic-auth \ + --no-issue-client-certificate \ + --project=$PROJECT_ID \ + --region=us-central1 \ + --machine-type=n1-standard-4 \ + --image-type=cos \ + --num-nodes=1 \ + --cluster-version=latest + ``` + + Note that + [the `--scopes` argument to `gcloud container cluster create`](https://cloud.google.com/sdk/gcloud/reference/container/clusters/create#--scopes) + controls what GCP resources the cluster's default service account has access + to; for example to give the default service account full access to your GCR + registry, you can add `storage-full` to your `--scopes` arg. + +1. Grant cluster-admin permissions to the current user: + + ```bash + kubectl create clusterrolebinding cluster-admin-binding \ + --clusterrole=cluster-admin \ + --user=$(gcloud config get-value core/account) + ``` + +## Environment Setup + +To [run your controllers with `ko`](#install-triggers) you'll need to set these +environment variables (we recommend adding them to your `.bashrc`): + +1. `GOPATH`: If you don't have one, simply pick a directory and add + `export GOPATH=...` +1. `$GOPATH/bin` on `PATH`: This is so that tooling installed via `go get` will + work properly. +1. `KO_DOCKER_REPO`: The docker repository to which developer images should be + pushed (e.g. `gcr.io/[gcloud-project]`). You can also run a local registry + and set `KO_DOCKER_REPO` to reference the registry (e.g. at + `localhost:5000/myimages`). + +`.bashrc` example: + +```shell +export GOPATH="$HOME/go" +export PATH="${PATH}:${GOPATH}/bin" +export KO_DOCKER_REPO='gcr.io/my-gcloud-project-name' +``` + +Make sure to configure +[authentication](https://cloud.google.com/container-registry/docs/advanced-authentication#standalone_docker_credential_helper) +for your `KO_DOCKER_REPO` if required. To be able to push images to +`gcr.io/`, you need to run this once: + +```shell +gcloud auth configure-docker +``` + +The user you are using to interact with your k8s cluster must be a cluster admin +to create role bindings: + +```shell +# Using gcloud to get your current user +USER=$(gcloud config get-value core/account) +# Make that user a cluster admin +kubectl create clusterrolebinding cluster-admin-binding \ + --clusterrole=cluster-admin \ + --user="${USER}" +``` + +## Install Pipelines + +To install [Tekton Pipelines](https://github.com/tektoncd/pipeline) you can +either: + +* [Install a released version](https://github.com/tektoncd/pipeline/blob/master/docs/install.md) +* [Setup Tekton Pipelines for development](https://github.com/tektoncd/pipeline/blob/master/DEVELOPMENT.md) + (install and iterate from HEAD) + +## Iterating + +While iterating on the project, you may need to: + +1. [Install/Run Pipelines](#install-pipelines) +1. [Install/Run Triggers](#install-triggers) +1. Verify it's working by [looking at the logs](#accessing-logs) +1. Update your (external) dependencies with: `./hack/update-deps.sh`. + + **Running dep ensure manually, will pull a bunch of scripts deleted + [here](./hack/update-deps.sh#L29)** + +1. Update your type definitions with: `./hack/update-codegen.sh`. +1. [Add new CRD types](#adding-new-types) +1. [Add and run tests](./test/README.md#tests) + +To make changes to these CRDs, you will probably interact with +(**Note this code doesn't yet exist!!**): + +- The CRD type definitions in + [./pkg/apis/triggers/alpha1](./pkg/apis/triggers/v1alpha1) +- The reconcilers in [./pkg/reconciler](./pkg/reconciler) +- The clients are in [./pkg/client](./pkg/client) (these are generated by + `./hack/update-codegen.sh`) + +### Install Triggers + +**Note: this is aspirational! We don't yet have any code or config to deploy, +watch this space!** + +You can stand up a version of this controller on-cluster (to your +`kubectl config current-context`): + +```shell +ko apply -f config/ +``` + +### Redeploy controller + +As you make changes to the code, you can redeploy your controller with: + +```shell +ko apply -f config/controller.yaml +``` + +### Tear it down + +You can clean up everything with: + +```shell +ko delete -f config/ +``` + +## Accessing logs + +To look at the controller logs, run: + +```shell +kubectl -n tekton-pipelines logs $(kubectl -n tekton-pipelines get pods -l app=tekton-triggers-controller -o name) +``` + +To look at the webhook logs, run: + +```shell +kubectl -n tekton-pipelines logs $(kubectl -n tekton-pipelines get pods -l app=tekton-triggers-webhook -o name) +``` + +## Adding new types + +If you need to add a new CRD type, you will need to add: + +1. A yaml definition in [config/](./config) +1. Add the type to the cluster roles in + [200-clusterrole.yaml](./config/200-clusterrole.yaml) diff --git a/code-of-conduct.md b/code-of-conduct.md new file mode 100644 index 000000000..a79210610 --- /dev/null +++ b/code-of-conduct.md @@ -0,0 +1,75 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of +experience, education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, +offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at +tekton-code-of-conduct@googlegroups.com. All complaints will be reviewed and +investigated and will result in a response that is deemed necessary and +appropriate to the circumstances. The project team is obligated to maintain +confidentiality with regard to the reporter of an incident. Further details of +specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.4, available at +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org \ No newline at end of file diff --git a/test/README.md b/test/README.md new file mode 100644 index 000000000..d788ff290 --- /dev/null +++ b/test/README.md @@ -0,0 +1,4 @@ +# Tests + +This directory will eventually contain end to end tests and libs to support +unit tests.