Skip to content

Commit

Permalink
Format markdown
Browse files Browse the repository at this point in the history 
Produced via: `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github)`
  • Loading branch information
@mattmoor-sockpuppet @knative-prow-robot
mattmoor-sockpuppet authored and knative-prow-robot committed Dec 5, 2018
1 parent d2eb6ef commit e5fe6eb
Show file tree
Hide file tree
Showing 16 changed files with 524 additions and 333 deletions.
119 changes: 70 additions & 49 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,88 +1,104 @@
# Contributing to Pipeline CRD

Welcome to the Pipeline CRD project! Thanks for considering contributing to our project and we hope you'll enjoy it :D
Welcome to the Pipeline CRD 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).**
**All contributors must comply with
[the code of conduct](./code-of-conduct.md).**

To get started developing, see our [DEVELOPMENT.md](./DEVELOPMENT.md).

In this file you'll find info on:

- [Principles](#principles)
- [The pull request process](#pull-request-process) and [Prow commands](#prow-commands)
- [Standards](#standards) around [commit messages](#commit-messages) and [code](#coding-standards)
- [The pull request process](#pull-request-process) and
[Prow commands](#prow-commands)
- [Standards](#standards) around [commit messages](#commit-messages) and
[code](#coding-standards)
- [Finding something to work on](#finding-something-to-work-on)
- [The roadmap](#roadmap)
- [Contacting other contributors](#contact)

_See also [the contribution guidelines for Knative](https://github.com/knative/docs/blob/master/community/CONTRIBUTING.md)._
_See also
[the contribution guidelines for Knative](https://github.com/knative/docs/blob/master/community/CONTRIBUTING.md)._

## Principles

When possbile, try to practice:

- **Documentation driven development** - Before implementing anything, write docs to explain
how it will work
- **Test driven development** - Before implementing anything, write tests to cover it
- **Documentation driven development** - Before implementing anything, write
docs to explain how it will work
- **Test driven development** - Before implementing anything, write tests to
cover it

Minimize the number of integration tests written and maximize the unit tests! Unit test
coverage should increase or stay the same with every PR.
Minimize the number of integration tests written and maximize the unit tests!
Unit test coverage should increase or stay the same with every PR.

This means that most PRs should include both:

- Tests
- Documentation explaining features being added, including updates to [DEVELOPMENT.md](./DEVELOPMENT.md) if required
- Documentation explaining features being added, including updates to
[DEVELOPMENT.md](./DEVELOPMENT.md) if required

## Pull Request Process

This repo uses [Prow](https://github.com/kubernetes/test-infra/tree/master/prow)
and related tools like [Tide](https://github.com/kubernetes/test-infra/tree/master/prow/tide)
and [Gubernator](https://github.com/kubernetes/test-infra/tree/master/gubernator)
(see [Knative Prow](https://github.com/knative/test-infra/blob/master/ci/prow/prow_setup.md)).
and related tools like
[Tide](https://github.com/kubernetes/test-infra/tree/master/prow/tide) and
[Gubernator](https://github.com/kubernetes/test-infra/tree/master/gubernator)
(see
[Knative Prow](https://github.com/knative/test-infra/blob/master/ci/prow/prow_setup.md)).
This means that automation will be applied to your pull requests.

_See also [Knative docs on reviewing](https://github.com/knative/docs/blob/master/community/REVIEWING.md)._
_See also
[Knative docs on reviewing](https://github.com/knative/docs/blob/master/community/REVIEWING.md)._

### Prow configuration

Prow is configured in [the knative `config.yaml` in `knative/test-infra`](https://github.com/knative/test-infra/blob/master/ci/prow/config.yaml)
Prow is configured in
[the knative `config.yaml` in `knative/test-infra`](https://github.com/knative/test-infra/blob/master/ci/prow/config.yaml)
via the sections for `knative/build-pipeline`.

### Prow commands

Prow has a [number of commands](https://prow.knative.dev/command-help) you can use to interact with it.
More on the Prow proces in general
Prow has a [number of commands](https://prow.knative.dev/command-help) you can
use to interact with it. More on the Prow proces in general
[is available in the k8s docs](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process).

#### Getting sign off

Before a PR can be merged, it must have both `/lgtm` AND `/approve`:

- `/lgtm` can be added by anyone in [the knative org](https://github.com/orgs/knative/people)
- `/approve` can be added only by [OWNERS](https://github.com/knative/build-pipeline/blob/master/OWNERS)
- `/lgtm` can be added by anyone in
[the knative org](https://github.com/orgs/knative/people)
- `/approve` can be added only by
[OWNERS](https://github.com/knative/build-pipeline/blob/master/OWNERS)

[OWNERS](https://github.com/knative/build-pipeline/blob/master/OWNERS) automatically get `/approve`
but still will need an `/lgtm` to merge.
[OWNERS](https://github.com/knative/build-pipeline/blob/master/OWNERS)
automatically get `/approve` but still will need an `/lgtm` to merge.

The merge will happen automatically once the PR has both `/lgtm` and `/approve`,
and all tests pass. If you don't want this to happen you should [`/hold`](#preventing-the-merge)
the PR.
and all tests pass. If you don't want this to happen you should
[`/hold`](#preventing-the-merge) the PR.

Any changes will cause the `/lgtm` label to be removed and it will need to be re-applied.
Any changes will cause the `/lgtm` label to be removed and it will need to be
re-applied.

#### Preventing the merge

If you don't a PR to be merged, e.g. so that the author can make changes, you can put it on hold with `/hold`.
Remove the hold with `/hold cancel`.
If you don't a PR to be merged, e.g. so that the author can make changes, you
can put it on hold with `/hold`. Remove the hold with `/hold cancel`.

#### Tests

If you are a member of [the knative org](https://github.com/orgs/knative/people), tests (required to merge)
will be automatically kicked off for your PR. If not,
[someone with `/lgtm` or `/approve` permission](#getting-sign-off)
will need to add `/ok-to-test` to your PR to allow the tests to run.
If you are a member of
[the knative org](https://github.com/orgs/knative/people), tests (required to
merge) will be automatically kicked off for your PR. If not,
[someone with `/lgtm` or `/approve` permission](#getting-sign-off) will need to
add `/ok-to-test` to your PR to allow the tests to run.

When tests (run by Prow) fail, it will add a comment to the PR with the commands to re-run any failing tests
When tests (run by Prow) fail, it will add a comment to the PR with the commands
to re-run any failing tests

#### Cats and dogs

Expand All @@ -94,12 +110,13 @@ This section describes the standards we will try to maintain in this repo.

### Commit Messages

All commit messages should follow [these best practices](https://chris.beams.io/posts/git-commit/),
specifically:
All commit messages should follow
[these best practices](https://chris.beams.io/posts/git-commit/), specifically:

- Start with a subject line
- Contain a body that explains _why_ you're making the change you're making
- Reference an issue number one exists, closing it if applicable (with text such as
- Reference an issue number one exists, closing it if applicable (with text such
as
["Fixes #245" or "Closes #111"](https://help.github.com/articles/closing-issues-using-keywords/))

Aim for [2 paragraphs in the body](https://www.youtube.com/watch?v=PJjmw9TRB7s).
Expand All @@ -119,36 +136,39 @@ The code in this repo should follow best practices, specifically:

## Finding something to work on

Thanks so much for considering contributing to our project!! We hope very much you can find something
interesting to work on:
Thanks so much for considering contributing to our project!! We hope very much
you can find something interesting to work on:

- To find issues that we particularly would like contributors to tackle, look for
- To find issues that we particularly would like contributors to tackle, look
for
[issues with the "help wanted" label](https://github.com/knative/build-pipeline/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
- Issues that are good for new folks will additionally be marked with
["good first issue"](https://github.com/knative/build-pipeline/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

### Assigning yourself an issue

To assign an issue to a user (or yourself), use GitHub or the Prow command by writing a comment
in the issue such as:
To assign an issue to a user (or yourself), use GitHub or the Prow command by
writing a comment in the issue such as:

```none
/assign @your_github_username
```

Unfortunately, GitHub will only allow issues to be assigned to users who are part of
[the knative org](https://github.com/orgs/knative/people).
Unfortunately, GitHub will only allow issues to be assigned to users who are
part of [the knative org](https://github.com/orgs/knative/people).

But don't let that stop you! **Leave a comment in the issue indicating you would like to work
on it** and we will consider it assigned to you.
But don't let that stop you! **Leave a comment in the issue indicating you would
like to work on it** and we will consider it assigned to you.

## Roadmap

As of Nov 2018, our goal for the end of the year is to get the project into a usable state by
releasing a 0.0.1 version, also known as our Alpha version. At this point the API should be relatively
stable and we would feel confident inviting users to start trying out the project.
As of Nov 2018, our goal for the end of the year is to get the project into a
usable state by releasing a 0.0.1 version, also known as our Alpha version. At
this point the API should be relatively stable and we would feel confident
inviting users to start trying out the project.

This work is visible in [the Alpha 0.0.1 milestone](https://github.com/knative/build-pipeline/milestone/2).
This work is visible in
[the Alpha 0.0.1 milestone](https://github.com/knative/build-pipeline/milestone/2).

## Contact

Expand All @@ -158,4 +178,5 @@ If you are interested please join our meetings and or in slack at
[`#build-pipeline`](https://knative.slack.com/messages/build-pipeline)!

All docs shared with this group are made visible to members of
[knative-dev@](https://groups.google.com/forum/#!forum/knative-dev), please join if you are interested!
[knative-dev@](https://groups.google.com/forum/#!forum/knative-dev), please join
if you are interested!
80 changes: 49 additions & 31 deletions DEVELOPMENT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,28 @@
## Getting started

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. 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)

Then you can [iterate](#iterating) (including [runing the controllers with `ko`](#install-pipeline)).
Then you can [iterate](#iterating) (including
[runing the controllers with `ko`](#install-pipeline)).

### Checkout your fork

The Go tools require that you clone the repository to the `src/github.com/knative/build-pipeline` directory
in your [`GOPATH`](https://github.com/golang/go/wiki/SettingGOPATH).
The Go tools require that you clone the repository to the
`src/github.com/knative/build-pipeline` 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. Create your own
[fork of this repo](https://help.github.com/articles/fork-a-repo/)
1. Clone it to your machine:

```shell
Expand All @@ -34,41 +36,49 @@ git remote add upstream git@github.com:knative/build-pipeline.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/)._
_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 `Pipeline CRD` is built in
1. [`go`](https://golang.org/doc/install): The language `Pipeline CRD` 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/go-containerregistry/tree/master/cmd/ko): For
development.
1. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For interacting with your kube cluster
1. [`ko`](https://github.com/google/go-containerregistry/tree/master/cmd/ko):
For development.
1. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For
interacting with your kube cluster

## Kubernetes cluster

To setup a cluster with GKE:

1. [Install required tools and setup GCP project](https://github.com/knative/docs/blob/master/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`).
(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 for knative](https://github.com/knative/docs/blob/master/install/Knative-with-GKE.md#creating-a-kubernetes-cluster)

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.
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.

## Environment Setup

To [run your controllers with `ko`](#install-pipeline) you'll need to set these environment
variables (we recommend adding them to your `.bashrc`):
To [run your controllers with `ko`](#install-pipeline) 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]`).
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]`).

`.bashrc` example:

Expand All @@ -78,14 +88,17 @@ 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/<project>`, you need to run this once:
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/<project>`, 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:
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
Expand All @@ -104,22 +117,26 @@ While iterating on the project, you may need to:
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)**
**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:

- The CRD type definitions in [./pkg/apis/pipeline/alpha1](./pkg/apis/pipeline/v1alpha1)
- The CRD type definitions in
[./pkg/apis/pipeline/alpha1](./pkg/apis/pipeline/v1alpha1)
- The reconcilers in [./pkg/reconciler](./pkg/reconciler)
- The clients are in [./pkg/client](./pkg/client) (these are generated by `./hack/update-codegen.sh`)
- The clients are in [./pkg/client](./pkg/client) (these are generated by
`./hack/update-codegen.sh`)

## Install Pipeline

You can stand up a version of this controller on-cluster (to your `kubectl config current-context`),
including `knative/build` (which is wrapped by [`Task`](docs/Concepts.md#task)):
You can stand up a version of this controller on-cluster (to your
`kubectl config current-context`), including `knative/build` (which is wrapped
by [`Task`](docs/Concepts.md#task)):

```shell
ko apply -f config/
Expand Down Expand Up @@ -162,4 +179,5 @@ kubectl -n knative-build-pipeline logs $(kubectl -n knative-build-pipeline get p
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)
1. Add the type to the cluster roles in
[200-clusterrole.yaml](./config/200-clusterrole.yaml)
Loading

0 comments on commit e5fe6eb

Please sign in to comment.