From 3358641372ab1602a228b0e618e78883e54a84e8 Mon Sep 17 00:00:00 2001 From: Mike Brown Date: Fri, 29 Apr 2016 15:04:03 -0500 Subject: devel/ tree 80col wrap and other minor edits Signed-off-by: Mike Brown --- development.md | 76 +++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 25 deletions(-) (limited to 'development.md') diff --git a/development.md b/development.md index d08dc3d2..3e782e03 100644 --- a/development.md +++ b/development.md @@ -47,7 +47,8 @@ branch, but release branches of Kubernetes should not change. ## Building Kubernetes Official releases are built using Docker containers. To build Kubernetes using -Docker please follow [these instructions](http://releases.k8s.io/HEAD/build/README.md). +Docker please follow [these +instructions](http://releases.k8s.io/HEAD/build/README.md). ### Go development environment @@ -55,14 +56,16 @@ Kubernetes is written in the [Go](http://golang.org) programming language. To build Kubernetes without using Docker containers, you'll need a Go development environment. Builds for Kubernetes 1.0 - 1.2 require Go version 1.4.2. Builds for Kubernetes 1.3 and higher require Go version 1.6.0. If you -haven't set up a Go development environment, please follow [these instructions](http://golang.org/doc/code.html) -to install the go tools and set up a GOPATH. +haven't set up a Go development environment, please follow [these +instructions](http://golang.org/doc/code.html) to install the go tools and set +up a GOPATH. To build Kubernetes using your local Go development environment (generate linux binaries): hack/build-go.sh -You may pass build options and packages to the script as necessary. To build binaries for all platforms: +You may pass build options and packages to the script as necessary. To build +binaries for all platforms: hack/build-cross.sh @@ -82,7 +85,9 @@ Other git workflows are also valid. ### Clone your fork -The commands below require that you have $GOPATH set ([$GOPATH docs](https://golang.org/doc/code.html#GOPATH)). We highly recommend you put Kubernetes' code into your GOPATH. Note: the commands below will not work if +The commands below require that you have $GOPATH set ([$GOPATH +docs](https://golang.org/doc/code.html#GOPATH)). We highly recommend you put +Kubernetes' code into your GOPATH. Note: the commands below will not work if there is more than one directory in your `$GOPATH`. ```sh @@ -108,7 +113,9 @@ git fetch upstream git rebase upstream/master ``` -Note: If you have write access to the main repository at github.com/kubernetes/kubernetes, you should modify your git configuration so that you can't accidentally push to upstream: +Note: If you have write access to the main repository at +github.com/kubernetes/kubernetes, you should modify your git configuration so +that you can't accidentally push to upstream: ```sh git remote set-url --push upstream no_push @@ -116,9 +123,10 @@ git remote set-url --push upstream no_push ### Committing changes to your fork -Before committing any changes, please link/copy the pre-commit hook -into your .git directory. This will keep you from accidentally -committing non-gofmt'd Go code. In addition this hook will do a build. +Before committing any changes, please link/copy the pre-commit hook into your +.git directory. This will keep you from accidentally committing non-gofmt'd Go +code. This hook will also do a build and test whether documentation generation +scripts need to be executed. The hook requires both Godep and etcd on your `PATH`. @@ -156,15 +164,22 @@ See [Faster Reviews](faster_reviews.md) for more details. ## godep and dependency management -Kubernetes uses [godep](https://github.com/tools/godep) to manage dependencies. It is not strictly required for building Kubernetes but it is required when managing dependencies under the Godeps/ tree, and is required by a number of the build and test scripts. Please make sure that ``godep`` is installed and in your ``$PATH``. +Kubernetes uses [godep](https://github.com/tools/godep) to manage dependencies. +It is not strictly required for building Kubernetes but it is required when +managing dependencies under the Godeps/ tree, and is required by a number of the +build and test scripts. Please make sure that ``godep`` is installed and in your +``$PATH``. ### Installing godep -There are many ways to build and host Go binaries. Here is an easy way to get utilities like `godep` installed: +There are many ways to build and host Go binaries. Here is an easy way to get +utilities like `godep` installed: -1) Ensure that [mercurial](http://mercurial.selenic.com/wiki/Download) is installed on your system. (some of godep's dependencies use the mercurial -source control system). Use `apt-get install mercurial` or `yum install mercurial` on Linux, or [brew.sh](http://brew.sh) on OS X, or download -directly from mercurial. +1) Ensure that [mercurial](http://mercurial.selenic.com/wiki/Download) is +installed on your system. (some of godep's dependencies use the mercurial +source control system). Use `apt-get install mercurial` or `yum install +mercurial` on Linux, or [brew.sh](http://brew.sh) on OS X, or download directly +from mercurial. 2) Create a new GOPATH for your tools and install godep: @@ -182,7 +197,8 @@ export PATH=$PATH:$GOPATH/bin ``` Note: -At this time, godep update in the Kubernetes project only works properly if your version of godep is < 54. +At this time, godep update in the Kubernetes project only works properly if your +version of godep is < 54. To check your version of godep: @@ -193,11 +209,14 @@ godep v53 (linux/amd64/go1.5.3) ### Using godep -Here's a quick walkthrough of one way to use godeps to add or update a Kubernetes dependency into `vendor/`. For more details, please see the instructions in [godep's documentation](https://github.com/tools/godep). +Here's a quick walkthrough of one way to use godeps to add or update a +Kubernetes dependency into `vendor/`. For more details, please see the +instructions in [godep's documentation](https://github.com/tools/godep). 1) Devote a directory to this endeavor: -_Devoting a separate directory is not required, but it is helpful to separate dependency updates from other changes._ +_Devoting a separate directory is not required, but it is helpful to separate +dependency updates from other changes._ ```sh export KPATH=$HOME/code/kubernetes @@ -240,20 +259,27 @@ go get -u path/to/dependency godep update path/to/dependency/... ``` -_If `go get -u path/to/dependency` fails with compilation errors, instead try `go get -d -u path/to/dependency` -to fetch the dependencies without compiling them. This can happen when updating the cadvisor dependency._ +_If `go get -u path/to/dependency` fails with compilation errors, instead try +`go get -d -u path/to/dependency` to fetch the dependencies without compiling +them. This can happen when updating the cadvisor dependency._ -5) Before sending your PR, it's a good idea to sanity check that your Godeps.json file is ok by running `hack/verify-godeps.sh` +5) Before sending your PR, it's a good idea to sanity check that your +Godeps.json file is ok by running `hack/verify-godeps.sh` -_If hack/verify-godeps.sh fails after a `godep update`, it is possible that a transitive dependency was added or removed but not -updated by godeps. It then may be necessary to perform a `godep save ./...` to pick up the transitive dependency changes._ +_If hack/verify-godeps.sh fails after a `godep update`, it is possible that a +transitive dependency was added or removed but not updated by godeps. It then +may be necessary to perform a `godep save ./...` to pick up the transitive +dependency changes._ -It is sometimes expedient to manually fix the /Godeps/godeps.json file to minimize the changes. +It is sometimes expedient to manually fix the /Godeps/godeps.json file to +minimize the changes. -Please send dependency updates in separate commits within your PR, for easier reviewing. +Please send dependency updates in separate commits within your PR, for easier +reviewing. -6) If you updated the Godeps, please also update `Godeps/LICENSES` by running `hack/update-godep-licenses.sh`. +6) If you updated the Godeps, please also update `Godeps/LICENSES` by running +`hack/update-godep-licenses.sh`. ## Testing -- cgit v1.2.3