-
Notifications
You must be signed in to change notification settings - Fork 100
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: update prerequisite with dev container
Signed-off-by: Christian Lechner <[email protected]>
- Loading branch information
1 parent
6016160
commit a9bfd5f
Showing
6 changed files
with
155 additions
and
75 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,22 +1,55 @@ | ||
| # Repository Prerequisites | ||
|
|
||
| This page lists the prerequisites for working with the repository. Most contributors should start with the basic prerequisites. Depending on the task you need to perform, you may need to install more tools. | ||
| This page lists the prerequisites for working with the repository. In general, you have three options to get your development setup up and running: | ||
|
|
||
| - Remotely using GitHub Codespaces | ||
| - Locally using Visual Studio Code and dev containers leveraging | ||
| - Locally by installing all prerequisites on your | ||
|
|
||
| We will walk you through the options in the following sections. | ||
|
|
||
| > 📝 **Tip** - We recommend the usage of GitHub Codespaces of local dev containers as they are the most convenient way to get started. | ||
| Depending on the task you need to perform, you may need to install more tools, but basic prerequisites should be sufficient for most contributors to get started. | ||
|
|
||
| ## Operating system | ||
|
|
||
| We support developing on macOS, Linux and Windows with [WSL](https://docs.microsoft.com/windows/wsl/install). | ||
|
|
||
| ## Asking for help | ||
|
|
||
| If you get stuck installing any of our dependencies, please ask for help in our [forum](https://discordapp.com/channels/1113519723347456110/1115302284356767814). | ||
| If you get stuck with any development setup option, please ask for help in our [forum](https://discordapp.com/channels/1113519723347456110/1115302284356767814). | ||
|
|
||
| ## Editors | ||
|
|
||
| If you don't have a code editor set up for Go, we recommend VS Code. The experience with VS Code is high-quality and approachable for newcomers. | ||
|
|
||
| Alternatively, you can choose whichever editor you are most comfortable for working on Go code. Feel free to skip this section if you want to make another choice. | ||
|
|
||
| - [Visual Studio Code](https://code.visualstudio.com/) | ||
| - [Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go) | ||
|
|
||
| Install both of these and then follow the steps in the *Quick Start* for the Go extension. | ||
|
|
||
| The extension will walk you through an automated install of some additional tools that match your installed version of Go. | ||
|
|
||
| **Launching VS Code** | ||
|
|
||
| The best way to launch VS Code for Go is to do *File* -> *Open Folder* on the repository. | ||
|
|
||
| You can easily do this from the command shell with `code .`, which opens the current directory as a folder in VS Code. | ||
|
|
||
| ## Tool Overview | ||
|
|
||
| Contributing to Project Radius requires several tools to get started. This section lists them grouped by their context | ||
|
|
||
| ## Basic Prerequisites | ||
| > 📝 **Tip** - If your are using GitHub Codespaces or Dev Containers, all these tools are already in place. The following sections give you an overview what tools you have at hand in these environments. You directly jump to section [GitHub Codespaces](#github-codespaces) or [VS Code and Dev Container](#vs-code-and-dev-container). | ||
| <!-- | ||
| Note: some of this content is synchronized with the first-commit guide for simplicity. Keep these in sync! | ||
| --> | ||
|
|
||
| ### Required tools | ||
| ### Required Tools | ||
|
|
||
| This is the list of core dependencies to install for the most common tasks. In general we expect all contributors to have all of these tools present: | ||
|
|
||
|
|
@@ -26,100 +59,130 @@ This is the list of core dependencies to install for the most common tasks. In g | |
| - [Python](https://www.python.org/downloads/) | ||
| - [Golangci-lint](https://golangci-lint.run/usage/install/#local-installation) | ||
| - [jq](https://jqlang.github.io/jq/download/) | ||
| - Make | ||
|
|
||
| **Linux**: Install the `build-essential` package: | ||
| ```bash | ||
| sudo apt-get install build-essential | ||
| ``` | ||
| **Mac**: | ||
| Using Xcode: | ||
| ```bash | ||
| xcode-select --install | ||
| ``` | ||
| Using Homebrew: | ||
| ```bash | ||
| brew install make | ||
| ``` | ||
| - Make | ||
|
|
||
| To build our containers, you also need [Docker](https://docs.docker.com/engine/install/). | ||
|
|
||
| #### Testing Required Tools | ||
| ### Additional Tools | ||
|
|
||
| If you have not already done so, clone the repository and navigate there in your command shell. | ||
| The following tools are required depending on the task at hand. | ||
|
|
||
| You can build the main outputs using `make`: | ||
| ### Kubernetes | ||
|
|
||
| ```sh | ||
| make build && make lint | ||
| ``` | ||
| The easiest way to run Radius is on Kubernetes. To do this you will need the ability to create a Kubernetes cluster as well as to install `kubectl` to control that cluster, you probably also want Helm to install things in your cluster. There are many ways to create a Kubernetes cluster that you can use for development and testing. If you don't have a preference we recommend `kind`. | ||
|
|
||
| Running these steps will run our build and lint steps and verify that the tools are installed correctly. If you get stuck or suspect something is not working in these instructions please [open an issue](https://github.com/radius-project/radius/issues/new/choose). | ||
| - [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) | ||
| - [Install Helm](https://helm.sh/docs/intro/install/) | ||
| - [Install Kind](https://kubernetes.io/docs/tasks/tools/#kind) | ||
|
|
||
| ### Editor | ||
| #### Troubleshooting Kubernetes | ||
|
|
||
| If you don't have a code editor set up for Go, we recommend VS Code. The experience with VS Code is high-quality and approachable for newcomers. | ||
| You might want tools that can help debug Kubernetes problems and understand what's going on in the cluster. Here are some recommendations from the team: | ||
|
|
||
| Alternatively, you can choose whichever editor you are most comfortable for working on Go code. Feel free to skip this section if you want to make another choice. | ||
| - [Lens (UI for Kubernetes)](https://k8slens.dev/) | ||
| - [VS Code Kubernetes Tools](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-kubernetes-tools) | ||
| - [Stern (console logging tool)](https://github.com/stern/stern#installation) | ||
|
|
||
| #### Dapr | ||
|
|
||
| Radius includes integration with [Dapr](https://docs.dapr.io/). To use work on these features, you'll need to install the Dapr CLI. | ||
|
|
||
| - [Dapr](https://docs.dapr.io/getting-started/install-dapr-cli/) | ||
|
|
||
| #### Test summaries | ||
|
|
||
| The default `go test` output can be hard to read when you have many tests. We recommend `gotestsum` as a tool to solve this. Our `make test` command will automatically use `gotestsum` if it is available. | ||
|
|
||
| - [gotestsum](https://github.com/gotestyourself/gotestsum#install) | ||
|
|
||
| ## Development Environment - Setup Options | ||
|
|
||
| The following sections describe the aforementioned alternatives of development setups in more detail. | ||
|
|
||
| ### GitHub Codespaces | ||
|
|
||
| The easiest way to get started is using our pre-built GitHub Codespace. | ||
|
|
||
| The steps to execute are: | ||
|
|
||
| 1. Press this button[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=340522752&skip_quickstart=true&machine=basicLinux32gb&devcontainer_path=.devcontainer%2Fcontributor%2Fdevcontainer.json&geo=UsWest) | ||
| 1. There is no second step - you are ready to contribute 😎 | ||
|
|
||
| > **Note** - When using GitHub Codespoces cost can occur on your side after you have used up the monthly included storage and core hours for your account. You find more details [here](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). | ||
| ### VS Code and Dev Container | ||
|
|
||
| To use the dev container locally you must have the following tools installed and running locally: | ||
|
|
||
| - [Visual Studio Code](https://code.visualstudio.com/) | ||
| - [Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go) | ||
| - [Dev Container Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) | ||
| - [Docker](https://docs.docker.com/engine/install/) | ||
|
|
||
| Install both of these and then follow the steps in the *Quick Start* for the Go extension. | ||
| To get the Dev Container up and running | ||
|
|
||
| The extension will walk you through an automated install of some additional tools that match your installed version of Go. | ||
| 1. If not already done, clone your fork of the Project Radius repository to your local file system and open the folder with VS Code. | ||
| 1. Click the "X"-like button in VS Code to open a remote window | ||
|  | ||
|
|
||
| **Launching VSCode** | ||
| 1. Select the option "Reopen in Container" in the command palette | ||
|  | ||
|
|
||
| The best way to launch VS Code for Go is to do *File* -> *Open Folder* on the repository. | ||
| The dev container will be started automatically. | ||
|  | ||
|
|
||
| You can easily do this from the command shell with `code .`, which opens the current directory as a folder in VS Code. | ||
| When doing this the first time this might take a bit as all dependencies need to be downloaded and installed in your container - so grab a cup of ☕ and enjoy the work done by the container. | ||
|
|
||
| ## Additional Tools | ||
| Once the container is up and running you can start with your contribution. | ||
|
|
||
| ### Containers | ||
| > 📝 **Tip** - You find more information about developing inside a container [here](https://code.visualstudio.com/docs/devcontainers/containers) | ||
| [Docker](https://docs.docker.com/engine/install/) is required to build our containers. | ||
| ### Local Installation | ||
|
|
||
| ### Kubernetes | ||
| to have all prerequisites installed locally you must install the tools mentioned in the sections [Tool Overview - Required Tools](#required-tools) and [Tool Overview - Additional Tools](#additional-tools) on your local machine. | ||
|
|
||
| The easiest way to run Radius is on Kubernetes. To do this you will need the ability to create a Kubernetes cluster as well as to install `kubectl` to control that cluster, you probably also want Helm to install things in your cluster. There are many ways to create a Kubernetes cluster that you can use for development and testing. If you don't have a preference we recommend `kind`. | ||
| For `make` we advice the following steps depending on you OS: | ||
|
|
||
| **Linux**: Install the `build-essential` package: | ||
|
|
||
| - [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) | ||
| - [Install Helm](https://helm.sh/docs/intro/install/) | ||
| - [Install Kind](https://kubernetes.io/docs/tasks/tools/#kind) | ||
| ```bash | ||
| sudo apt-get install build-essential | ||
| ``` | ||
|
|
||
| #### Troubleshooting Kubernetes | ||
| **Mac**: | ||
| Using Xcode: | ||
|
|
||
| You might want tools that can help debug Kubernetes problems and understand what's going on in the cluster. Here are some recommendations from the team: | ||
| ```bash | ||
| xcode-select --install | ||
| ``` | ||
|
|
||
| - [Lens (UI for Kubernetes)](https://k8slens.dev/) | ||
| - [VS Code Kubernetes Tools](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-kubernetes-tools) | ||
| - [Stern (console logging tool)](https://github.com/stern/stern#installation) | ||
| Using Homebrew: | ||
|
|
||
| ### Dapr | ||
| ```bash | ||
| brew install make | ||
| ``` | ||
|
|
||
| Radius includes integration with [Dapr](https://docs.dapr.io/). To use work on these features, you'll need to install the Dapr CLI. | ||
| ## Testing Required Tools | ||
|
|
||
| - [Dapr](https://docs.dapr.io/getting-started/install-dapr-cli/) | ||
| Independent of the setup option you have chosen, you can now test your tooling. If not already done, navigate to the cloned project in your command shell and build the main outputs using `make`: | ||
|
|
||
| ```bash | ||
| make build && make lint | ||
| ``` | ||
|
|
||
| Running these steps will run our build and lint steps and verify that the tools are installed correctly. If you get stuck or suspect something is not working in these instructions please [open an issue](https://github.com/radius-project/radius/issues/new/choose). | ||
|
|
||
| ### Code Generation | ||
|
|
||
| Our code generation targets are used to update generated OpenAPI specs and generated Go code based on those OpenAPI specs. Additionally, some Go code is generated mocks or Kubernetes API types. | ||
| Our code generation targets are used to update generated OpenAPI specs and generated Go code based on those OpenAPI specs. Additionally, some Go code is generated mocks or Kubernetes API types. | ||
|
|
||
| If you were trying to run `make generate` and ran into an error, then one of the below is likely missing. | ||
| If you were trying to run `make generate` and ran into an error, then one of the below is likely missing. | ||
|
|
||
| Enter the following commands to install all of the required tools. | ||
|
|
||
| ```sh | ||
| ```bash | ||
| cd typespec && npm ci | ||
| npm install -g autorest | ||
| npm install -g oav | ||
| go install sigs.k8s.io/controller-tools/cmd/[email protected] | ||
| go install github.com/golang/mock/[email protected] | ||
| ``` | ||
|
|
||
| ### Test summaries | ||
|
|
||
| The default `go test` output can be hard to read when you have many tests. We recommend `gotestsum` as a tool to solve this. Our `make test` command will automatically use `gotestsum` if it is available. | ||
|
|
||
| - [gotestsum](https://github.com/gotestyourself/gotestsum#install) | ||
Binary file added
BIN
+588 KB
...uting-code/contributing-code-prerequisites/img/vscode-cmd-palette-container.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+48.1 KB
.../contributing-code-prerequisites/img/vscode-devcontainer-open-remote-button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+189 KB
...ode/contributing-code-prerequisites/img/vscode-devcontainer-opening-process.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.