diff --git a/site/content/docs/contributing/getting-started.md b/site/content/docs/contributing/getting-started.md index 69f3587417..4bfd99bf42 100644 --- a/site/content/docs/contributing/getting-started.md +++ b/site/content/docs/contributing/getting-started.md @@ -20,44 +20,51 @@ 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. -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. @@ -91,6 +98,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 @@ -101,7 +109,8 @@ 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/ @@ -109,3 +118,4 @@ See also: the Kubernetes [community page]. [@BenTheElder]: https://github.com/BenTheElder [@munnerz]: https://github.com/munnerz [community page]: http://kubernetes.io/community/ +[modules]: https://github.com/golang/go/wiki/Modules diff --git a/site/content/docs/contributing/project-scope.md b/site/content/docs/contributing/project-scope.md index 1661754db4..a170acb181 100644 --- a/site/content/docs/contributing/project-scope.md +++ b/site/content/docs/contributing/project-scope.md @@ -36,19 +36,20 @@ 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 @@ -56,9 +57,9 @@ See also: the [1.0 roadmap], and the [1.0 tracking milestone]. **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**: @@ -68,6 +69,11 @@ 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 @@ -75,8 +81,9 @@ however there is some additional work. **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 --- @@ -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] ❤️ 🦒 ❤️ - ... @@ -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