Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

improve contributor docs #314

Merged
merged 3 commits into from
Feb 18, 2019
Merged

improve contributor docs #314

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
95e77fa
improve contributor guide
BenTheElder Feb 18, 2019
7b0fb9a
add more links to project scope and flesh out slightly more
BenTheElder Feb 18, 2019
7fdd3e4
do not specify git version
BenTheElder Feb 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 34 additions & 22 deletions site/content/docs/contributing/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,44 +20,53 @@ an account to contribute.

## 2. Install Tools

### Install Documentation Tools
### Install git

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:
Our source code is managed with [`git`][git], to develop locally you
will need to install `git`.

* `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.
This documentation is written using `git` version `2.17.1`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

written -> managed?

also possibly no need to add this sentence?
users without git will land with a fairly new and compatible git package as a download.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SGTM, this was already in the doc, I only changed the command / version markup to match. Will remove.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Your version may be different depending on your OS.

#### Install or upgrade Go
### Install Hugo

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 Go

To work on kind's codebase you will need [Go][golang].

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].
Preferably Go `1.11.5` or greater should be installed.

Correct automatic formatting of the source with `gofmt` requires at least
`1.11.0`.

Working with Go [modules] (which we use for dependency management) requires at
least `1.11.4` due to checksum bugs in lower versions.

### Install Docker

Currently, to create clusters you will need to install [Docker][docker].

If you haven't already, [install Docker][install docker], following the
[official instructions][install docker].
If you have an existing installation, check your version and make sure you have
the latest Docker.

Expand Down Expand Up @@ -91,6 +100,7 @@ reach out if you have any questions!

See also: the Kubernetes [community page].

[git]: https://git-scm.com/
[hugo]: https://gohugo.io
[issues]: https://github.com/kubernetes-sigs/kind/issues
[file an issue]: https://github.com/kubernetes-sigs/kind/issues/new
Expand All @@ -101,11 +111,13 @@ See also: the Kubernetes [community page].
[initial design]: /docs/design/initial
[github]: https://github.com/
[golang]: https://golang.org/doc/install
[docker]: https://docs.docker.com/install/#supported-platforms
[docker]: https://www.docker.com/
[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/
[modules]: https://github.com/golang/go/wiki/Modules
49 changes: 33 additions & 16 deletions site/content/docs/contributing/project-scope.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,29 +36,30 @@ See also: the [1.0 roadmap], and the [1.0 tracking milestone].

**Stakeholders**:

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

**Covered Work**:

- Limited workloads / e2e testing
- Cluster bring-up (IE kubeadm)
- Limited workloads / [e2e testing][e2e]
- 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)
- Node skew, client skew (kubectl / e2e versions)
- Image publishing
- Kubernetes CI tooling and jobs
- Kubernetes CI tooling and [jobs][kubeadm-kind-job]
- Most everything in the [1.0 roadmap]
- ...

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

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

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

**Covered Work**:
Expand All @@ -68,15 +69,21 @@ Most of the necessary work should be covered under
however there is some additional work.

- Improve "kind as a library"
- better and more controllable logging
- generally more control over output
- example usage & documentation
- better / tighter API contracts
- Most of the rest should be covered by improving "kind the binary" outlined above
- ...

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

**Stakeholders**:

- The cluster-api
- cluster-api-provider-foo developers
- various [cluster-api][cluster-api] [provider implementation][cluster-api provider implementations]
developers
- various [cluster-api][cluster-api] users

### P3: Extended Testing Not Covered Above
---
Expand All @@ -102,9 +109,9 @@ Several of these make sense but are not possible with the current tooling and wi

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.
- Cloud provider / [CCM]
- Some of the node testing (which portions exactly is currently unclear)
- Being an alternative to "docker compose" etc.
- Replacing [Phippy][phippy] ❤️ 🦒 ❤️
- ...

Expand All @@ -113,3 +120,13 @@ Some things we can likely never cover in a reasonable way:
[1.0 roadmap]: /docs/contributing/1.0-roadmap
[1.0 tracking milestone]: https://github.com/kubernetes-sigs/kind/milestone/2
[phippy]: https://phippy.io
[kubeadm]: https://github.com/kubernetes/kubeadm
[sigs]: https://github.com/kubernetes/community/blob/master/sig-list.md
[e2e]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/e2e-tests.md
[kubeadm-kind-job]: https://testgrid.k8s.io/sig-cluster-lifecycle-all#kubeadm-kind-master
[cert-manager]: https://github.com/jetstack/cert-manager
[cluster-api-provider-aws]: https://github.com/kubernetes-sigs/cluster-api-provider-aws
[cluster-api-provider-azure]: https://github.com/kubernetes-sigs/cluster-api-provider-azure
[cluster-api]: https://github.com/kubernetes-sigs/cluster-api
[cluster-api provider implementations]: https://github.com/kubernetes-sigs/cluster-api#provider-implementations
[CCM]: https://github.com/kubernetes/kubernetes/tree/master/cmd/cloud-controller-manager