Skip to content

Latest commit

 

History

History
81 lines (67 loc) · 7.57 KB

CONTRIBUTING.md

File metadata and controls

81 lines (67 loc) · 7.57 KB

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 3.1 (or later) 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 [email protected]:{your_username}/bicep.git.
  • Build the .NET solution with dotnet build. If this fails try running git submodule update --init --recursive first.

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

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, set the BICEP_LANGUAGE_SERVER_PATH environment variable found in launch.json manually following WSL environment setup scripts.
  • 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.
  • Pull Request validation will ensure that the main.bicep file can be compiled successfully without errors, and that the generated main.json file matches the one being checked in. If you want to validate that this will pass locally before submitting a PR, you can use dotnet test in the root directory of this repo to run the full test suite.

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 [email protected] with any additional questions or comments.