Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
182 lines (121 loc) · 4.42 KB

CONTRIBUTING.md

File metadata and controls

182 lines (121 loc) · 4.42 KB

Contribution Guide

Open issues and submitting pull requests are welcome! If you'd like to contribute code to this project, you can follow along with this guide to get started.

Development environment

There are two good ways of getting started:

Dev container

You can open this repository in either GitHub Codespaces or locally in a Dev container. All the prerequisite software required to contribute code in this project will be preinstalled.

Local development

You can also work in this codebase locally. You'll need the following prerequisites:

When you open VSCode, you should be prompted to install additional, recommended extensions, including rust-analyzer, the LLDB debugger, and more.

After cloning the repository, install Node.js dependencies:

npm install

Building

To build the workspace, in the root of the repository just run:

cargo build

Testing

To run unit tests:

cargo test

Integration and manual tests require a Key Vault. To provision a vault with the Azure Developer CLI, run:

# Environment name 'dev' recommended.
azd up

This will provision a vault and a few secrets for testing commands e.g.:

cargo run -- secret list
cargo run -- read --name secret-1

If you provision a vault using azd, a .env file is created under .azure/dev/.env by default, which this project will read automatically.

To provision secret variables for demonstration, source an appropriate setup script under the examples/ directory:

Bash

In bash - or almost any popular shell on linux or macOS:

# The script is not executable and requires sourcing.
. ./examples/setup.sh

PowerShell

In PowerShell:

# You can also invoke the script from within powershell.
. ./examples/setup.ps1

Manual testing

To manually test the CLI, install Pester in PowerShell and run:

azd up # If you haven't already

Invoke-Pester tests/test.ps1

Linting

Spell Checking

To check spelling:

npm run spell-check

To automatically fix spelling issues where possible:

npm run spell-check:fix

The spell checker uses cspell with configuration in .cspell.json. Add custom words to the words array in that file.

Markdown Linting

To lint markdown files:

npm run markdown-lint

To automatically fix markdown issues where possible:

npm run markdown-lint:fix

The markdown linter uses markdownlint-cli2 with configuration in .markdownlint-cli2.yaml.

Examples

Blobs

The blobs example is a simple demo application to list and read blobs. You need to create an app registration for RBAC initially, however:

az ad sp create-for-rbac -n akv-demo

Note the appId and password fields. You'll want to pass the appId when provisioning resources the first time:

AZURE_CLIENT_ID='{appId}' azd up

Once provisioning is complete and because the debug builds of akv will automatically read the azd environment care of dotazure, you can create client secret and retain the secret reference for azd:

cargo run -- secret create client-secret='{password}'
azd env set AZURE_CLIENT_SECRET '{ID from previous command}'

Now you can run the blobs example within the akv run command:

cargo run -- run -- cargo run --example blobs

Troubleshooting

To help troubleshoot issues, you can trace information to the terminal:

RUST_LOG=info,akv=debug cargo run -- secret list

The RUST_LOG environment variable here sets the default tracing level to info but debug for all akv traces.