Skip to content
Permalink
Browse files

expand contributing docs

  • Loading branch information...
BenTheElder committed Feb 14, 2019
1 parent 85200f5 commit e042d01a9c8e3ff1ef108dbe3064e3f106838773
@@ -21,7 +21,7 @@ kind consists of:

kind bootstraps each "node" with [kubeadm][kubeadm]. For more details see [the design documentation][design doc].

**NOTE**: kind is still a work in progress, see [docs/roadmap.md].
**NOTE**: kind is still a work in progress, see the [1.0 roadmap].

## Installation and usage

@@ -57,7 +57,7 @@ reach out if you have any questions!
Pull Requests are very welcome!
See the [issue tracker] if you're unsure where to start, or feel free to reach out to discuss.

See also: the Kubernetes [community page].
See also: our own [contributor guide] and the Kubernetes [community page].

## Why kind?

@@ -105,7 +105,8 @@ Participation in the Kubernetes community is governed by the [Kubernetes Code of
[filing an issue]: https://github.com/kubernetes-sigs/kind/issues/new
[Kubernetes Slack]: http://slack.k8s.io/
[#kind]: https://kubernetes.slack.com/messages/CEKK1KTN2/
[docs/roadmap.md]: ./docs/roadmap.md
[1.0 roadmap]: https://kind.sigs.k8s.io/docs/contributing/1.0-roadmap
[install docker]: https://docs.docker.com/install/
[@BenTheElder]: https://github.com/BenTheElder
[@munnerz]: https://github.com/munnerz
[contributor guide]: https://kind.sigs.k8s.io/docs/contributing/getting-started
@@ -141,6 +141,11 @@ a { color: #1f28f0; }
/* ensure images don't go off the page */
#content img { max-width: 100%; }

hr {
background: #333;
border: 1px solid #333;
}

/* code block styling */
pre {
background-color: #f3f4f4 !important;
@@ -37,8 +37,8 @@ sectionPagesMenu = "main"
url = "/docs/design/"
weight = 5
[[menu.main]]
identifier = "devel"
name = "Developer Guide"
title = "Developer Guide"
url = "/docs/devel/"
identifier = "contributing"
name = "Contributing"
title = "contributing"
url = "/docs/contributing/"
weight = 6
@@ -16,7 +16,7 @@ kind consists of:

kind bootstraps each "node" with [kubeadm][kubeadm]. For more details see [the design documentation][design doc].

**NOTE**: kind is still a work in progress, see the [roadmap].
**NOTE**: kind is still a work in progress, see the [1.0 roadmap].

## Installation and usage

@@ -55,7 +55,7 @@ reach out if you have any questions!
Pull Requests are very welcome!
See the [issue tracker] if you're unsure where to start, or feel free to reach out to discuss.

See also: the Kubernetes [community page].
See also: our own [contributor guide] and the Kubernetes [community page].

## Why kind?

@@ -99,13 +99,13 @@ Participation in the Kubernetes community is governed by the [Kubernetes Code of
[kubeadm]: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm/
[design doc]: ./docs/design/initial
[user guide]: ./docs/user/quick-start
[the docs]: ./docs
[SIG-Testing Mailing List]: https://groups.google.com/forum/#!forum/kubernetes-sig-testing
[issue tracker]: https://github.com/kubernetes-sigs/kind/issues
[filing an issue]: https://github.com/kubernetes-sigs/kind/issues/new
[Kubernetes Slack]: http://slack.k8s.io/
[#kind]: https://kubernetes.slack.com/messages/CEKK1KTN2/
[roadmap]: ./docs/roadmap
[1.0 roadmap]: /docs/contributing/1.0-roadmap
[install docker]: https://docs.docker.com/install/
[@BenTheElder]: https://github.com/BenTheElder
[@munnerz]: https://github.com/munnerz
[contributor guide]: /docs/contributing/getting-started
@@ -1,14 +1,15 @@
---
title: "Roadmap"
title: "1.0 Roadmap"
menu:
main:
identifier: "roadmap"
name: "Roadmap"
parent: "contributing"
identifier: "1.0-roadmap"
weight: 3
---
# Roadmap 🗺️

New year, new roadmap 🎉

This document outlines some goals, non-goals, and future aspirations for kind
as a project.

@@ -0,0 +1,111 @@
---
title: "Getting Started"
menu:
main:
parent: "contributing"
identifier: "getting started"
weight: 1
---
# Getting Started

Welcome! This guide covers how to get started contributing to kind.

## 1. Read the Kubernetes community guidelines

Make sure to read you read the [Kubernetes community guidelines][community].
In specific, read through the [Kubernetes contributor guidelines][contributor].

Additionally, note that kind is developed on [GitHub][github] and will require
an account to contribute.

## 2. Install Tools

### Install Documentation Tools

If you wish to contribute to the documentation, it is recommended but not
required to install [hugo], which we use to develop this site.

Please see: https://gohugo.io/getting-started/installing/

### Install Developer Tools

If you wish to contribute to kind's code you will need to install the following:

* `git`
* `go`
* `docker`

#### Install git
Install `git` on your local machine.
You can check if `git` is already on your system and properly installed with
the following command:

```
git --version
```
This documentation is written using `git` version 2.17.1.
Your version may be different depending on your OS.

#### Install or upgrade Go
Install or upgrade [Go using the instructions for your operating system][golang].
You can check if Go is in your system with the following command:

```
go version
```
This documentation is written using Go version 1.11+.

#### Install or upgrade Docker
If you haven't already, install the
[Docker software using the instructions for your operating system][docker].
If you have an existing installation, check your version and make sure you have
the latest Docker.

To check if `docker` is has been installed:
```
docker --version
```
This documentation is written using Docker version 18.09.0.

## 3. Read The Docs

The [design principles], [1.0 roadmap], [project structure], and [initial design]
may be helpful to review before contributing.

## 4. Reaching Out

Issues are tracked on GitHub. Please check [the issue tracker][issues] to see
if there is any existing dicussion or work related to your interests.

If you do not see anything, please [file a new issue][file an issue].

Please reach out for bugs, feature requests, and other issues!
The maintainers of this project are reachable via:

- [Kubernetes Slack] in the [#kind] channel
- [filing an issue][file an issue]
- The Kubernetes [SIG-Testing Mailing List]

Current maintainers are [@BenTheElder] and [@munnerz] - feel free to
reach out if you have any questions!

See also: the Kubernetes [community page].

[hugo]: https://gohugo.io
[issues]: https://github.com/kubernetes-sigs/kind/issues
[file an issue]: https://github.com/kubernetes-sigs/kind/issues/new
[design principles]: /docs/design/principles
[1.0 roadmap]: /docs/contributing/1.0-roadmap
[project scope]: /docs/contributing/project-scope
[project structure]: /docs/devel/project-structure
[initial design]: /docs/design/initial
[github]: https://github.com/
[golang]: https://golang.org/doc/install
[docker]: https://docs.docker.com/install/#supported-platforms
[community]: https://github.com/kubernetes/community
[contributor]: https://github.com/kubernetes/community/blob/master/contributors/guide/README.md
[Kubernetes Slack]: http://slack.k8s.io/
[#kind]: https://kubernetes.slack.com/messages/CEKK1KTN2/
[@BenTheElder]: https://github.com/BenTheElder
[@munnerz]: https://github.com/munnerz
[community page]: http://kubernetes.io/community/
@@ -0,0 +1,115 @@
---
title: "Project Scope"
menu:
main:
parent: "contributing"
identifier: "project-scope"
weight: 2
---
# Project Scope

This document outlines some scoping and major priorities for kind.

See also: the [1.0 roadmap], and the [1.0 tracking milestone].

## Priorities (from greatest to least)

### P-1: Bootstrapping the kind Project Itself
---

**Stakeholders**:

- kind maintainers
- kind contributors

**Covered Work**:

- Releases & tooling
- Automated image publishing
- Documentation bootstrapping (IE this site)
- Enough Kubernetes testing to test kind itself (Kubernetes Conformance tests)
- Setting up linters and other tools to verify quality
- Setting up a recurring subproject meeting

### P0: Support Testing Kubernetes
---

**Stakeholders**:

- SIG Testing
- SIG Cluster-Lifecycle
- the kubeadm subproject
- Possibly SIG Release (mainly to provide easy access to alpha and beta tags)

**Covered Work**:

- limited workloads / e2e testing
- cluster bring-up (IE kubeadm)
- kubernetes build (and currently install, but that may be problematic for cross-platform [#166])
- node skew, client skew (kubectl / e2e)
- image publishing
- Kubernetes CI tooling and jobs
- ...

### P1: Support Testing Kubernetes Applications
---

**Stakeholders**: Various projects both inside & outside the Kubernetes Org.

- cert-manager
- cluster-api-provider-aws
- cluster-api-provider-azure
- ...

**Covered Work**:

Most of the necessary work should be covered under
[P1: Support Testing Kubernetes Applications](#p1-support-testing-kubernetes-applications),
however there is some additional work.

- improve "kind as a library"
- ...

### P2: Provide Cheap Bootstrap Clusters for the Cluster-API
---

**Stakeholders**:

- the cluster-api
- cluster-api-provider-foo developers

### P3: Extended Testing Not Covered Above
---

**Stakeholders**:

- Indeterminate / many

Possibly supporting various things that we cannot reasonably test today including:

- "node" tests, e.g. reboot
- upgrades, downgrades
- anything depending on ingress
- anything depending on persistent storage / PVs
- testing the cluster-api proper with some sort of machine provisioning
- device plugin, e.g. GPU
- ...

Several of these make sense but are not possible with the current tooling and will require a reasonable amount of design and thought to do well. Some of them may not be solve-able in a good way, but are at least technologically feasible to explore.

### Out of Scope
---

Some things we can likely never cover in a reasonable way:

- cloud provider / CCM
- some of the node testing
- being a strange alternative library to "docker compose" etc.
- replacing [Phippy][phippy] ❤️ 🦒 ❤️
- ...


[#166]: https://github.com/kubernetes-sigs/kind/issues/166
[1.0 roadmap]: /docs/contributing/1.0-roadmap
[1.0 tracking milestone]: https://github.com/kubernetes-sigs/kind/milestone/2
[phippy]: https://phippy.io
@@ -2,7 +2,7 @@
title: "Project Structure"
menu:
main:
parent: "devel"
parent: "contributing"
identifier: "project-structure"
---
# Project Structure
@@ -90,6 +90,16 @@ In other words:
- Strive for reproducibility of operations
- Avoid depending on external services, vendor / pre-pull dependencies

## No External State

State is offloaded into the "node" containers in the form of labels, files in
the container filesystem, and processes in the container. The cluster itself
stores all state. No external state stores are used and the only stateful
process is the container runtime. kind does not itself store or manage state.

This simplifes a lot of problems and eases portability, while forcing cluster
interactions to be consistent.

## Consider Automation

While kind strives to present a pleasant UX to users on their local machines,
Oops, something went wrong.

0 comments on commit e042d01

Please sign in to comment.
You can’t perform that action at this time.