Skip to content

Latest commit

 

History

History
114 lines (81 loc) · 9.93 KB

CONTRIBUTING.md

File metadata and controls

114 lines (81 loc) · 9.93 KB
Raw

Contributing to Bicep

We are very happy to accept community contributions to Bicep, whether those are Pull Requests, Example Files, Feature Suggestions or Bug Reports! Please note that by participating in this project, you agree to abide by the Code of Conduct, as well as the terms of the CLA.

Getting Started

  • If you haven't already, you will need dotnet core sdk 5.0.100 and node + npm 10 (or later) installed locally to build and run this project.
  • You are free to work on Bicep on any platform using any editor, but you may find it quickest to get started using VSCode with the C# extension.
  • Fork this repo (see this forking guide for more information).
  • Checkout the repo locally with git clone git@github.com:{your_username}/bicep.git.
  • If git status shows untracked files in the bicep-types-az directory, remove the directory via rm -r bicep-types-az on Linux/Mac or rmdir /S bicep-types-az on Windows. (This is only needed once.)
  • Build the .NET solution with dotnet build.

Developing

Components

The Bicep solution is comprised of the following main components:

  • Bicep CLI (src/Bicep.Cli): the bicep CLI exectuable.
  • Bicep Language Server (src/Bicep.LangServer): the LanguageServer used by the VSCode extension for parsing and providing information about a Bicep file.
  • Bicep Core (src/Bicep.Core): the library containing the majority of the Bicep compiler code.
  • Bicep VSCode Extension (src/vscode-bicep): the VSCode extension itself. This is mostly a thin wrapper around the Bicep Language Server.
  • Playground (src/playground): the web-based playground hosted at https://aka.ms/bicepdemo.
  • A number of different test suites.

Running the tests

  • You can use the following command to run the full Bicep test suite:
    • dotnet test

Updating test baselines

  • Many of the bicep integration tests rely on baseline test assertion files that are checked into the repo. Code changes in some areas will require updates to the baseline assertions.
  • If you see a test failure with a message containing Windows and *nix copy commands, you have encountered such a test. You have the following options to fix the test:
    1. Manually execute the provided command in a shell. This makes sense for a single test, but is extremely tedious otherwise.
    2. Run the SetBaseline.ps1 script at the repo root to execute the tests in SetBaseLine mode, which causes the baselines to be automatically updated in bulk for failing tests. You should see baseline file modifications in Git pending changes. (Make sure your Git pending changes are empty before doing so - your changes could get overwritten!).
  • Inspect the baseline assertion diffs to ensure changes are expected and match the code changes you have made. (If a pull request contains changes to baseline files that can't be explained, it will not be merged.)

Running the Bicep VSCode extension

  • On the first run, you'll need to ensure you have installed all the npm packages required by the Bicep VSCode extension with the following:
    • cd src/vscode-bicep
    • npm i
  • In the VSCode Run View, select the "Bicep VSCode Extension" task, and press the "Start" button. This will launch a new VSCode window with the Bicep extension and LanguageServer containing your changes. When running on WSL, create a symbolic link in src/vscode-bicep named bicepLanguageServer to ../Bicep.LangServer/bin/Debug/net5.0.
  • If you want the ability to put breakpoints and step through the C# code, you can also use the "Attach" run configuration once the extension host has launched, and select the Bicep LanguageServer process by searching for "bicep".

Running the Bicep CLI

  • In the VSCode Run View, select the "Bicep CLI" task, and press the "Start" button. This will build and run the Bicep CLI and allow you to step through the code.
  • Note that usually you will want to pass your own custom arguments to the Bicep CLI. This can be done by modifying the launch.json configuration to add arguments to the "args" array for the "Bicep CLI" task.

Running the Playground

  • On the first run, you'll need to ensure you have installed all the npm packages required by the Bicep Playground with the following:
    • cd src/playground
    • npm i
  • In the VSCode Run View, select the "Bicep Playground" task, and press the "Start" button. This will launch a browser window with the Playground containing your changes.

Pull Requests

If you'd like to start contributing to Bicep, you can search for issues tagged as "good first issue" here.

Bicep Code

  • Ensure that an issue has been created to track the feature enhancement or bug that is being fixed.
  • In the PR description, make sure you've included "Fixes #{issue_number}" e.g. "Fixes #242" so that GitHub knows to link it to an issue.
  • To avoid multiple contributors working on the same issue, please add a comment to the issue to let us know you plan to work on it.
  • If a significant amount of design is required, please include a proposal in the issue and wait for approval before working on code. If there's anything you're not sure about, please feel free to discuss this in the issue. We'd much rather all be on the same page at the start, so that there's less chance that drastic changes will be needed when your pull request is reveiwed.
  • We report on code coverage; please ensure any new code you add is sufficiently covered by tests.

Example Files

If you'd like to contribute example .bicep files that showcase abilities of the language:

  • Create an appropriately-named directory inside docs/examples. Note that the directory naming matches that of the azure quickstart template repo.

  • Include your file named main.bicep.

  • Compile the file using the Bicep CLI, and include the compiled main.json with your check-in.

  • Update the src/playground/src/examples.ts to import the newly defined .bicep file and then add it to the examples object with the name you'd like it to appear in the playground

  • Pull Request validation checks the following:

    1. All .bicep files in docs/examples can be compiled without errors.
    2. All .bicep files have a corresponding .json file which exactly matches that generated by the Bicep compiler.
    3. All .bicep files have been formatted with the default Bicep auto-formatter.

    See Running the tests if you'd like to test locally before submitting a PR, and Updating test baselines for information on how to automatically update your example .json and .bicep files to match the format expected by the tests.

  • While everything will not necessarily be applicable, read through the Azure QuickStart Templates Best Practices Guide and follow it where appropriate (i.e. parameter guidance, resource property order, etc.)

Note: If you have never submitted a Pull Request or used git before, reading through the Git tutorial in the azure-quickstart-template repo is a good place to start.

Feature Suggestions

  • Please first search Open Bicep Issues before opening an issue to check whether your feature has already been suggested. If it has, feel free to add your own comments to the existing issue.
  • Ensure you have included a "What?" - what your feature entails, being as specific as possible, and giving mocked-up syntax examples where possible.
  • Ensure you have included a "Why?" - what the benefit of including this feature will be.
  • Use the "Feature Request" issue template here to submit your request.

Bug Reports

  • Please first search Open Bicep Issues before opening an issue, to see if it has already been reported.
  • Try to be as specific as possible, including the version of the Bicep CLI or extension used to reproduce the issue, and any example files or snippets of Bicep code needed to reproduce it.
  • Use the "Bug Report" issue template here to submit your request.

CLA

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.