diff --git a/docs/Contributing/Building-Fleet.md b/docs/Contributing/Building-Fleet.md index 41059af0f7..d4d146a57f 100644 --- a/docs/Contributing/Building-Fleet.md +++ b/docs/Contributing/Building-Fleet.md @@ -12,7 +12,7 @@ ### Quickstart -Install the dependencies as described in the next sections, then go to [Clone and build](#clone-and-build) +Install the dependencies as described in the following sections, then go to [Clone and build](#clone-and-build) #### macOS @@ -39,7 +39,7 @@ sudo npm install -g yarn #### Windows -To install dependencies, we recommend using [Chocolatey](https://chocolatey.org/install). Chocolatey must be run in Powershell as an Administrator. Assuming your setup does not include any of our requirements, please run: +To install dependencies, we recommend using [Chocolatey](https://chocolatey.org/install). Always run Chocolatey in Powershell as an Administrator. Assuming your setup does not include any of our requirements, please run: ``` choco install nodejs git golang docker make python2 mingw npm install -g yarn @@ -47,7 +47,7 @@ npm install -g yarn Note: all packages default to the latest versions. To specify a version, place `--version ` after each package. You may also install all packages manually from their websites if you prefer. -After the packages have installed, you must use **Git Bash** to continue with the [next section](#clone-and-build). +After installing the packages, you must use **Git Bash** to continue with the [next section](#clone-and-build). ### Clone and build @@ -63,7 +63,7 @@ The binaries are now available in `./build/`. ### Details -To setup a working local development environment, you must install the following minimum toolset: +To set up a working local development environment, you must install the following minimum toolset: * [Go](https://golang.org/doc/install) * [Node.js](https://nodejs.org/en/download/current/) and [Yarn](https://yarnpkg.com/en/docs/install) @@ -85,7 +85,7 @@ When pulling changes, it may be necessary to re-run `make deps` if a new Go or J ### Generating the packaged JavaScript -To generate all necessary code (bundling JavaScript into Go, etc), run the following: +To generate all necessary code (bundling JavaScript into Go, etc.), run the following: ``` make generate @@ -93,33 +93,33 @@ make generate #### Automatic rebuilding of the JavaScript bundle -Normally, `make generate` takes the JavaScript code, bundles it into a single bundle via Webpack, and inlines that bundle into a generated Go source file so that all of the frontend code can be statically compiled into the binary. When you build the code after running `make generate`, all of that JavaScript is included in the binary. +Usually, `make generate` takes the JavaScript code, bundles it into a single bundle via Webpack, and inlines that bundle into a generated Go source file so that all of the frontend code can be statically compiled into the binary. When you build the code after running `make generate`, include all of that JavaScript in the binary. -This makes deploying Fleet a dream, since you only have to worry about a single static binary. If you are working on frontend code, it is likely that you don't want to have to manually re-run `make generate` and `make build` every time you edit JavaScript and CSS in order to see your changes in the browser. To solve this problem, before you build the Fleet binary, run the following command instead of `make generate`: +This makes deploying Fleet a dream since you only have to worry about a single static binary. If you are working on frontend code, it is likely that you don't want to have to manually re-run `make generate` and `make build` every time you edit JavaScript and CSS in order to see your changes in the browser. Instead of running `make generate` to solve this problem, before you build the Fleet binary, run the following command: ``` make generate-dev ``` -Instead of reading the JavaScript from a inlined static bundle compiled within the binary, `make generate-dev` will generate a Go source file which reads the frontend code from disk and run Webpack in "watch mode". +Instead of reading the JavaScript from an inline static bundle compiled within the binary, `make generate-dev` will generate a Go source file which reads the frontend code from disk and run Webpack in "watch mode." -Note that when you run `make generate-dev`, Webpack will be watching the JavaScript files that were used to generate the bundle, so the process will be long lived. Depending on your personal workflow, you might want to run this in a background terminal window. +Note that when you run `make generate-dev`, Webpack will be watching the JavaScript files that were used to generate the bundle so that the process will be long-lived. Depending on your personal workflow, you might want to run this in a background terminal window. After you run `make generate-dev`, run `make build` to build the binary, launch the binary and you'll be able to refresh the browser whenever you edit and save frontend code. ### Compiling the Fleet binary -For convenience, a Makefile is included to build the code: +For convenience, Fleet includes a Makefile to build the code: ``` make ``` -It's not necessary to use Make to build the code, but using Make allows us to account for cross-platform differences more effectively than the `go build` tool when writing automated tooling. Use whichever you prefer. +It's unnecessary to use Make to build the code, but using Make allows us to account for cross-platform differences more effectively than the `go build` tool when writing automated tooling. Use whichever you prefer. ## Development infrastructure -The following assumes that [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) (installed by default with Docker on macOS and Windows) are installed. +The following assumes that you already installed [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) (installed by default with Docker on macOS and Windows). ### Starting the local development environment @@ -158,9 +158,9 @@ The server is accessible by default at [https://localhost:8080](https://localhos By default, Fleet will try to connect to servers running on default ports on `localhost`. Depending on your browser's settings, you may have to click through a security warning. -If you're using the Google Chrome web browser, you have the option to always automatically bypass the security warning. Visit [chrome://flags/#allow-insecure-localhost](chrome://flags/#allow-insecure-localhost) and set the "Allow invalid certificates for resources loaded from localhost." flag to "Enabled." +If you're using the Google Chrome web browser, you can always automatically bypass the security warning. Visit [chrome://flags/#allow-insecure-localhost](chrome://flags/#allow-insecure-localhost) and set the "Allow invalid certificates for resources loaded from localhost." flag to "Enabled." -> Note: in Chrome version 88 there is a bug where you must first enable [chrome://flags/#temporary-unexpire-flags-m87](chrome://flags/#temporary-unexpire-flags-m87). The [chrome://flags/#allow-insecure-localhost](chrome://flags/#allow-insecure-localhost) flag will then be visible again. +> Note: in Chrome version 88, there is a bug where you must first enable [chrome://flags/#temporary-unexpire-flags-m87](chrome://flags/#temporary-unexpire-flags-m87). The [chrome://flags/#allow-insecure-localhost](chrome://flags/#allow-insecure-localhost) flag will then be visible again. ## Debugging with Delve debugger @@ -173,7 +173,7 @@ Use the following command in place of `make` and `./build/fleet serve --dev`: dlv debug --build-flags '-tags=full' ./cmd/fleet -- serve --dev ``` -It is important to pass the `-tags=full` build flag, otherwise the server will not have access to the asset files. +It is important to pass the `-tags=full` build flag; otherwise, the server will not have access to the asset files. ### Attaching a debugger to a running server