Skip to content

Commit

Permalink
docs: rewrite contributing (#4355)
Browse files Browse the repository at this point in the history 
Rewrite contributing to assume little-to-no-prior knowledge of go.

Completes #4351
  • Loading branch information
@weikanglim
weikanglim authored Sep 20, 2024
1 parent bdcadc9 commit 3b48ae5
Show file tree
Hide file tree
Showing 4 changed files with 98 additions and 109 deletions.
1 change: 1 addition & 0 deletions .github/workflows/cli-ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ on:
pull_request:
paths:
- "cli/**"
- '!cli/docs/**'
- ".github/workflows/cli-ci.yml"
- "go.mod"
branches: [main]
Expand Down
164 changes: 56 additions & 108 deletions cli/azd/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,141 +1,85 @@
# Contributing to `azd`

## Prerequisites
Hi there 👋! Thank you for showing interest in contributing to `azd`.

`azd` is written in Golang and requires Go 1.20 or above:
In general, to make contributions a smooth and easy experience, we encourage the following:

- [Go](https://go.dev/dl/)
- Check existing issues for [bugs][bug issues] or [enhancements][enhancement issues].
- Open an issue if things aren't working as expected, or if an enhancement is being proposed.
- Start a conversation on the issue if you are thinking of submitting a pull request.
- Submit a pull request. The `azd` team will work with you to review the changes and provide feedback. Once the pull request is accepted, a member will merge the changes. Thank you for taking time out of your day to help improve our community!

If you don't have a preferred editor for Go code, we recommend [Visual Studio Code](https://code.visualstudio.com/Download).
We have a `settings.json` file checked in, so if you launch `code` from within `cli/azd` you should get our customizations.

While `azd` itself does not depend on the `az` CLI, some of our tests use it, so you should make sure you've installed it
and logged in.

- [AZ CLI](https://docs.microsoft.com/cli/azure/)

We have some additional linting tools that we run in CI, and you will want to be able to run locally:

- [golangci-lint](https://golangci-lint.run/welcome/install/#local-installation)

In order to run end-to-end tests and develop templates, you'll need the following dependencies:

Language tooling:

- [NodeJS](https://nodejs.org/en/download/)
- [Python](https://www.python.org/downloads)
- [DotNet CLI](https://get.dot.net)

Infrastructure-as-code providers:
## Building `azd`

- [Bicep CLI](https://aka.ms/bicep-install)
- [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) (if working on Terraform templates)
Prerequisites:

Docker:
- [Go](https://go.dev/dl/) 1.23

- [Docker](https://docs.docker.com/desktop/#download-and-install)
Build:

## Submitting A Change

We use a fork based workflow for `azd`. Here are simple steps:

1. Fork `azure/azure-dev` on GitHub.
2. Create a branch named `<some-description>` (e.g. `fix-123` for a bug fix or `add-deploy-command`) in your forked Git
repository.
3. Push the branch to your fork on GitHub.
4. Open a pull request in GitHub.

Here is a more [in-depth guide to forks in GitHub](https://guides.github.com/activities/forking/).

As part of CI validation, we run a series of live tests which provision and deprovision Azure resources. For external
contributors, these tests will not run automatically, but someone on the team will be able to run them for your PR on your
behalf.

## Debugging

In VS Code you can add a configuration to launch.json that runs the tool with a specified set of arguments and in a specific
folder, for example:

```json
{
"name": "dev-azd (launch)",
"type": "go",
"request": "launch",
"mode": "debug",
"program": "${workspaceFolder}",
"args": [
"restore"
],
"cwd": "${workspaceFolder}"
},
```bash
cd cli/azd
go build
```

You can also set `AZD_DEBUG=true` in your environment. If this environment variable is set, `azd` will pause early in its
startup process and allow you to attach to it. The checked in `launch.json` already has a configuration for this mode called
"Attach To Process".
Run the newly produced `azd` or `azd.exe` binary:

## Testing
- Unix-like systems: `./azd`
- Windows: `.\azd.exe`

We use `gotestsum`, which is a simple tool that wraps `go test` except with better formatting output. Install the tool by
running `go install gotest.tools/gotestsum@latest`.
Run tests:

### Run unit tests

`gotestsum -- -short ./...`

### Run end-to-end tests

`gotestsum -- -timeout 20m -run Test_CLI ./...`
```bash
go test ./... -short
```

This runs all end-to-end tests that target the standalone `azd` binary locally and **will** deploy live resources.
By default, the `azd` binary produced in the cli/azd folder is automatically built once if not up-to-date,
so it is sufficient to run end-to-end tests without having to first running `go build`.
Run tests (including end-to-end [functional][functional tests] tests)

If testing against a custom binary, set `CLI_TEST_AZD_PATH` explicitly. See test/azdcli package for more details.
```bash
go test ./...
```

### Run all tests
Run cspell (install [cspell](https://cspell.org/)):

```bash
gotestsum -- -timeout 20m ./...
cspell lint "**/*.go" --relative --config ./.vscode/cspell.yaml
```

### Run a specific test

`gotestsum -- -timeout 20m -run Test_CLI_RestoreCommand ./...`
Run linter (install [golangci-lint](https://golangci-lint.run/welcome/install/#local-installation)):

This can be useful for running specific end-to-end tests that cover the relevant scenarios.
```bash
golangci-lint run ./...
```

## Linting
> Note: On Windows you may need to add `C:\Program Files\Git\usr\bin` to `%PATH%`
Run `golangci-lint run ./...`
### Debugging (with VSCode)

> On Windows you may need to add `C:\Program Files\Git\usr\bin` to `%PATH%`
If you don't have a preferred editor for Go code, we recommend [Visual Studio Code](https://code.visualstudio.com/Download).

## Spell checking
Launch and debug:

1. Install [cspell](https://cspell.org/)
2. CD to /cli/azd
3. Run `cspell lint "**/*.go" --relative --config ./.vscode/cspell.yaml`
1. Open VSCode in either `cli/azd` (preferred) or in the root directory.
1. In VSCode, put a breakpoint on the line of code you would like to debug.
1. Press F5. Alternatively: Select the "Run and Debug" side pane. With the launch task set to "Debug azd cli", click on the launch button.
1. An interactive VSCode prompt should appear. Provide the args for running `azd` in this prompt window. Press enter when you're done.
1. `azd` should now be running inside the VSCode terminal with the debugger attached.

## Tracing
Launch `azd` separately, then attach:

`azd` supports logging trace information to either a file or an OpenTelemetry compatible HTTP endpoint. The
`--trace-log-file` can be used to write a JSON file containing all the spans for an command execution. Also,
`--trace-log-url` can be used to provide an endpoint to send spans using the OTLP HTTP protocol.
1. Set `AZD_DEBUG=true` in your shell. If this environment variable is set, `azd` will pause early in its startup process and allow you to attach to it.
1. In VSCode, run the launch task "Attach to process".
1. Select `azd` and press enter.
1. VSCode debugger should now be attached to the running `azd` process.
1. In the shell with `azd` running, press enter to resume execution.

You can use the Jaeger all in one docker image to run Jaeger locally to collect and inspect traces:
> Tip: Use the VSCode terminal to perform all `azd` build and run commands.
```
$ docker run -d --name jaeger \
-e COLLECTOR_OTLP_ENABLED=true \
-e JAEGER_DISABLED=true \
-p 16686:16686 \
-p 4318:4318 \
jaegertracing/all-in-one
```
## Submitting a change

And then pass `--trace-log-url localhost` to a command and view the results in the Jaeger UI served at
[http://localhost:16686/search](http://localhost:16686/search)
1. Create a new branch: `git checkout -b my-branch-name`
1. Make your change, add tests, and ensure tests pass
1. Submit a pull request: `gh pr create --web` (install [gh cli][gh cli] if needed). Select "Create a fork" to set up a fork for the first time if prompted for.

## Troubleshooting

Expand All @@ -144,10 +88,9 @@ And then pass `--trace-log-url localhost` to a command and view the results in t
Windows Security may block execution of unsigned .exe files. This may happen when validating unsigned .exe files produced in
a PR build.

```
```bash
> azd version
Access is denied.
>
```

To fix:
Expand All @@ -158,3 +101,8 @@ To fix:
1. Click the `Manage settings` link under `Virus & threat protection settings`
1. Scroll down in the window to the `Exclusions` heading and click the `Add or remove exclusions link`
1. Select `Add an exclusion` and add the path to the exe from step 1

[bug issues]: https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+label%3Abug
[enhancement issues]: https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
[functional tests]: https://github.com/Azure/azure-dev/tree/main/cli/azd/test/functional
[gh cli]: https://github.com/cli/cli?tab=readme-ov-file#installation
21 changes: 21 additions & 0 deletions cli/azd/docs/observability.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Observability

## Tracing

`azd` supports logging trace information to either a file or an OpenTelemetry compatible HTTP endpoint. The
`--trace-log-file` can be used to write a JSON file containing all the spans for an command execution. Also,
`--trace-log-url` can be used to provide an endpoint to send spans using the OTLP HTTP protocol.

You can use the Jaeger all in one docker image to run Jaeger locally to collect and inspect traces:

```bash
$ docker run -d --name jaeger \
-e COLLECTOR_OTLP_ENABLED=true \
-e JAEGER_DISABLED=true \
-p 16686:16686 \
-p 4318:4318 \
jaegertracing/all-in-one
```

And then pass `--trace-log-url localhost` to a command and view the results in the Jaeger UI served at
[http://localhost:16686/search](http://localhost:16686/search)
21 changes: 20 additions & 1 deletion docs/develop-templates.md → docs/CONTRIBUTING.templates.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,23 @@
# Developing Templates
# Contributing to templates stored in `azd`

## Pre-requisites

Language tooling:

- [NodeJS](https://nodejs.org/en/download/)
- [Python](https://www.python.org/downloads)
- [DotNet CLI](https://get.dot.net)

Infrastructure-as-code providers:

- [Bicep CLI](https://aka.ms/bicep-install)
- [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) (if working on Terraform templates)

Docker:

- [Docker](https://docs.docker.com/desktop/#download-and-install)

## Build templates

Unlike fully released [azd templates](https://github.com/topics/azd-templates), the template definition contained in this repository under the `templates` folder is disassembled into multiple directories. This allows re-use of specific assets such as Bicep files, resource assets, tests across templates. To reassemble the assets, a `repoman` file (`repo.yml`) is defined for each template that defines stitching and path rewriting via the `repoman generate` command. To learn more about the `repoman` tooling, see it's source under [generators/repo](../generators/repo).

Expand Down

0 comments on commit 3b48ae5

Please sign in to comment.