Skip to content

Latest commit

 

History

History
146 lines (99 loc) · 5.09 KB

CONTRIBUTING.md

File metadata and controls

146 lines (99 loc) · 5.09 KB

Contributing to azd

Hello there 👋! Thank you for showing interest in contributing to azd.

Guidelines

In general, to make contributions a smooth and easy experience, we encourage the following:

  • Check existing issues for bugs or enhancements.
  • 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!

Building azd

Prerequisites:

Build:

cd cli/azd
go build

Run the newly produced azd or azd.exe binary:

  • Unix-like systems: ./azd
  • Windows: .\azd.exe

Dev Install (build + add to PATH)

Install mage (go install github.com/magefile/mage@latest), then:

cd cli/azd
mage dev:install

This builds azd-dev (to avoid conflicting with a production azd install) with version info from cli/version.txt and the current git commit, installs it to ~/.azd/bin/, and automatically adds that directory to your PATH if it isn't already there.

Preflight (all quality checks)

Run all pre-commit checks (formatting, copyright headers, linting, spell check, build, unit tests) in one command:

cd cli/azd
mage preflight

Run tests:

go test ./... -short

Run tests (including end-to-end functional tests)

go test ./...

Run cspell (install cspell):

cspell lint "**/*.go" --relative --config ./.vscode/cspell.yaml

Run linter (install golangci-lint):

golangci-lint run ./...

Run code modernization check (go fix):

go fix -diff ./...

If go fix -diff reports any changes, apply them with go fix ./... and commit the result. CI enforces this check — PRs with pending go fix suggestions will fail the lint workflow.

Note: On Windows you may need to add C:\Program Files\Git\usr\bin to %PATH%

Debugging (with VSCode)

If you don't have a preferred editor for Go code, we recommend Visual Studio Code.

Launch and debug:

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

Launch azd separately, then attach:

  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.
  2. In VSCode, run the launch task "Attach to process".
  3. Select azd and press enter.
  4. VSCode debugger should now be attached to the running azd process.
  5. In the shell with azd running, press enter to resume execution.

Tip: Use the VSCode terminal to perform all azd build and run commands.

Submitting a change

  1. Create a new branch: git checkout -b my-branch-name
  2. Make your change, add tests, and ensure tests pass
  3. Submit a pull request: gh pr create --web (install gh cli if needed). Select "Create a fork" to set up a fork for the first time if prompted for.

Troubleshooting

Access is denied

Windows Security may block execution of unsigned .exe files. This may happen when validating unsigned .exe files produced in a PR build.

> azd version
Access is denied.

To fix:

  1. Run where azd (cmd) or (Get-Command azd).Source (PowerShell) to get the command path
  2. Click the Start button and type Windows Security, select and launch the "Windows Security" application
  3. Select Virus & threat protection tab on the left side of the window
  4. Click the Manage settings link under Virus & threat protection settings
  5. Scroll down in the window to the Exclusions heading and click the Add or remove exclusions link
  6. Select Add an exclusion and add the path to the exe from step 1