github.com/grahambrereton-form3/tilt@v0.10.18/DEVELOPING.md (about) 1 # Hacking on Tilt 2 3 So you want to make a change to `tilt`! 4 5 ## Contributing 6 7 We welcome contributions, either as bug reports, feature requests, or pull requests. 8 9 We want everyone to feel at home in this repo and its environs; please see our [**Code of Conduct**](https://docs.tilt.dev/code_of_conduct.html) for some rules that govern everyone's participation. 10 11 Most of this page describes how to get set up making & testing changes. 12 13 Small PRs are better than large ones. If you have an idea for a major feature, please file 14 an issue first. The [Roadmap](ROADMAP.md) has details on some of the upcoming 15 features that we have in mind and might already be in-progress. 16 17 ## Build Prereqs 18 19 If you just want to build Tilt: 20 21 - **[make](https://www.gnu.org/software/make/)** 22 - **[go 1.12](https://golang.org/dl/)** 23 - **[errcheck](https://github.com/kisielk/errcheck)**: `go get -u github.com/kisielk/errcheck` (to run lint) 24 - [yarn](https://yarnpkg.com/lang/en/docs/install/) (for JS resources) 25 26 ## Test Prereqs 27 28 If you want to run the tests: 29 30 - **[docker](https://docs.docker.com/install/)** - Many of the `tilt` build steps do work inside of containers 31 so that you don't need to install extra toolchains locally (e.g., the protobuf compiler). 32 - **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)** 33 - **[kustomize 2.0 or higher](https://github.com/kubernetes-sigs/kustomize)**: `go get -u sigs.k8s.io/kustomize` 34 - **[helm](https://docs.helm.sh/using_helm/#installing-helm)** 35 - **[docker compose](https://docs.docker.com/compose/install/)**: NOTE: this doesn't need to be installed separately from Docker on macOS 36 - **[jq](https://stedolan.github.io/jq/download/)** 37 38 ## Optional Prereqs 39 40 Other development commands: 41 42 - **[goimports](https://godoc.org/golang.org/x/tools/cmd/goimports)**: `go get -u golang.org/x/tools/cmd/goimports` (to sort imports, IDE-specific installation instructions in the link). You should configure goimports to run with `-local github.com/windmill/tilt` 43 - **[toast](https://github.com/stepchowfun/toast)**: `curl https://raw.githubusercontent.com/stepchowfun/toast/master/install.sh -LSfs | sh` Used for generating some protobuf files 44 - Our Python scripts are in Python 3.6.0. To run them: 45 - **[pyenv](https://github.com/pyenv/pyenv#installation)** 46 - **python**: `pyenv install` 47 - if you're using GKE and get the error: "pyenv: python2: command not found", run: 48 - `git clone git://github.com/concordusapps/pyenv-implict.git ~/.pyenv/plugins/pyenv-implict` 49 50 ## Developing 51 52 To check out Tilt for the first time, run: 53 54 ``` 55 go get -u github.com/windmilleng/tilt/cmd/tilt 56 ``` 57 58 The Go toolchain will checkout the Tilt repo somewhere on your GOPATH, 59 usually under `~/go/src/github.com/windmilleng/tilt`. (See notes below if you're using Go modules). 60 61 To run the fast test suite, run: 62 63 ``` 64 make shorttest 65 ``` 66 67 To run the slow test suite that interacts with Docker and builds real images, run: 68 69 ``` 70 make test 71 ``` 72 73 If you want to run an integration test suite that deploys servers to Kubernetes and 74 verifies them, run: 75 76 ``` 77 make integration 78 ``` 79 80 To install `tilt` on PATH, run 81 82 ``` 83 make install 84 ``` 85 86 To start using Tilt, just run `tilt up` in any project with a `Tiltfile` -- i.e., NOT the root of the Tilt source code. 87 There are plenty of toy projects to play with in the [integration](https://github.com/windmilleng/tilt/tree/master/integration) directory 88 (see e.g. `./integration/oneup`), or check out one of these sample repos to get started: 89 - [ABC123](https://github.com/windmilleng/abc123): Go/Python/JavaScript microservices generating random letters and numbers 90 - [Servantes](https://github.com/windmilleng/servantes): a-little-bit-of-everything sample app with multiple microservices in different languages, showcasing many different Tilt behaviors 91 - [Frontend Demo](https://github.com/windmilleng/tilt-frontend-demo): Tilt + ReactJS 92 - [Live Update Examples](https://github.com/windmilleng/live_update): contains Go and Python examples of Tilt's [Live Update](https://docs.tilt.dev/live_update_tutorial.html) functionality 93 - [Sidecar Example](https://github.com/windmilleng/sidecar_example): simple Python app and home-rolled logging sidecar 94 95 ### Go Modules 96 97 Currently, Tilt will not work with Go modules. See [this issue](https://github.com/windmilleng/tilt/issues/1520) 98 for more details. 99 100 If you're building Tilt from source, you must build it in your GOPATH. 101 102 103 ## Performance 104 ### Go Profile 105 We use the built-in Go profiler to debug performance issues. 106 107 When `tilt` is running, press `ctrl-p` to start the profile, and `ctrl-p` to stop it. 108 You should see output like: 109 110 ``` 111 starting pprof profile to tilt.profile 112 stopped pprof profile to tilt.profile 113 ``` 114 115 This means that Tilt has successfully written profiling data to the file `tilt.profile`. 116 In the directory where you ran Tilt, run: 117 118 ``` 119 go tool pprof tilt.profile 120 ``` 121 122 to open a special REPL that lets you explore the data. 123 Type `web` in the REPL to see a CPU graph. 124 125 For more information on pprof, see https://github.com/google/pprof/blob/master/doc/README.md. 126 127 ### Opentracing 128 If you're trying to diagnose Tilt performance problems that lie between Tilt and your Kubernetes cluster (or between Tilt and Docker) traces can be helpful. The easiest way to get started with Tilt's [opentracing](https://opentracing.io/) support is to use the [Jaeger all-in-one image](https://www.jaegertracing.io/docs/1.11/getting-started/#all-in-one). 129 130 ``` 131 $ docker run -d --name jaeger \ 132 -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \ 133 -p 5775:5775/udp \ 134 -p 6831:6831/udp \ 135 -p 6832:6832/udp \ 136 -p 5778:5778 \ 137 -p 16686:16686 \ 138 -p 14268:14268 \ 139 -p 9411:9411 \ 140 jaegertracing/all-in-one:1.11 141 ``` 142 143 Then start Tilt with the following flags: 144 145 ``` 146 tilt up --trace --traceBackend jaeger 147 ``` 148 149 When Tilt starts one of the first lines in the log output should contain a trace ID, like so: 150 151 ``` 152 TraceID: 26256f1f6aa875e5 153 ``` 154 155 You can use the Jaeger UI (by default running on http://localhost:16686/) to query for this span and see all of the traces for the current Tilt run. These traces are made available immediately as you use Tilt. You don't need to wait until after Tilt has stopped to get access to the tracing data. 156 157 ## Web UI 158 159 `tilt` uses a web interface for logs investigation. 160 161 By default, the web interface runs on port 10350. 162 163 When you use a released version of Tilt, all the HTML, CSS, and JS assets are served from our 164 [production bucket](https://console.cloud.google.com/storage/browser/tilt-static-assets). 165 166 When you build Tilt from head, the Tilt binary will default to development mode. 167 When you run Tilt, it will run a webpack dev server as a separate process on port 46764, 168 and reverse proxy all asset requests to the dev server. 169 170 To manually control the assets served, you can use: 171 172 ``` 173 tilt up --web-mode=local 174 ``` 175 176 to force Tilt to use the webpack dev server, or you can use 177 178 ``` 179 tilt up --web-mode=prod 180 ``` 181 182 to force Tilt to use production assets. 183 184 185 To run the server on an alternate port (e.g. 8001): 186 187 ``` 188 tilt up --port=8001 189 ``` 190 191 ## Documentation 192 193 The landing page and documentation lives in 194 [the tilt.build repo](https://github.com/windmilleng/tilt.build/). 195 196 We write our docs in Markdown and generate static HTML with [Jekyll](https://jekyllrb.com/). 197 198 Netlify will automatically deploy the docs to [the public site](https://docs.tilt.dev/) 199 when you merge to master. 200 201 ## Releasing 202 203 We use [goreleaser](https://goreleaser.com) for releases. 204 205 Requirements: 206 - goreleaser: `go get -u github.com/goreleaser/goreleaser` 207 - MacOS 208 - Python 209 - [gsutil](https://cloud.google.com/storage/docs/gsutil_install) 210 - `GITHUB_TOKEN` env variable with repo scope 211 212 Currently, releases have to be built on MacOS due to cross-compilation issues with Apple FSEvents. 213 Cross-compiling a Linux target binary with a MacOS toolchain works fine. 214 215 To create a new release at tag `$TAG`: 216 217 ``` 218 git fetch --tags 219 git tag -a v0.0.1 -m "my release" 220 git push origin v0.0.1 221 make release 222 ``` 223 224 goreleaser will build binaries for the latest tag (using semantic version to 225 determine "latest"). Check the current releases to figure out what the latest 226 release ought to be. 227 228 After updating the release notes, 229 update the [install](https://github.com/windmilleng/tilt.build/tree/master/docs/install.md) and [upgrade](https://github.com/windmilleng/tilt.build/blob/master/docs/upgrade.md) docs, 230 the [default dev version](internal/cli/build.go), 231 and the [installer version](scripts/install.sh). 232 233 ### Version numbers 234 For pre-v1.0: 235 * If adding backwards-compatible functionality increment the patch version (0.x.Y). 236 * If adding backwards-incompatible functionality increment the minor version (0.X.y). We would probably **write a blog post** about this. 237 238 ### Releasing the Synclet 239 240 Releasing a synclet should be very infrequent, because the amount of things it 241 does is small. (It's basically an optimization over `kubectl cp`, `kubectl 242 exec`, and restarting a container.) 243 244 To release a synclet, run `make synclet-release`. This will automatically: 245 246 - Publish a new synclet image tagged with the current date 247 - Update [sidecar.go](internal/synclet/sidecar/sidecar.go) with the new tag 248 249 Then submit the PR. The next time someone releases Tilt, it will use the new image tag. 250 251 252