Skip to content

Latest commit

 

History

History
71 lines (46 loc) · 4.25 KB

CONTRIBUTING.md

File metadata and controls

71 lines (46 loc) · 4.25 KB
Raw

Contributing to Bicep PowerShell

You are more than welcome to contribute to the Bicep PowerShell module, whether it is Pull Requests, Feature Suggestions or Bug Reports!

Getting Started

  • Fork this repo (see this forking guide for more information).
  • Checkout the repo locally with git clone [email protected]:{your_username}/PSBicep.git.
  • Run the command .\build.ps1 -ResolveDependency -Task build to download the required dependencies and build the module.

BicepNet

The Bicep PowerShell module uses a nested module named BicepNet. BicepNet is a thin wrapper around Bicep that will load all Bicep assemblies in a separate context to avoid conflicts with other modules, like Az PowerShell. It is BicepNet that controls which Bicep version is used by the module. When a new Bicep version is released BicepNet must be updated before the Bicep module can leverage the new features.

Structure

The repo is organized as below:

  • Classes (Source/Classes): Home of all the classes used by the module.
  • en-US (Source/en-US): Module help file location. Generated by PlatyPS from markdown help files in the Docs.
  • Private (Source/Private): All private functions used by the module.
  • Public (Source/Public): All functions exported by the module.
  • Tests (Tests): Pester tests executed at Pull Request.
  • scripts (scripts): Script file location used by Github Actions and to update assemblies when developing locally.
  • Help (Docs\Help): Markdown help files for external help.

Running the module locally

  • Download the assemblies needed by the module by running the command .\build.ps1 -ResolveDependency -Task build:
.\build.ps1 -ResolveDependency -Task build
  • Import the module:
Import-Module .\Source\Bicep.psd1

platyPS

platyPS is used to write the external help in markdown. When contributing always make sure that the changes are added to the help file.
A slightly modified version of platyPS is downloaded and used by the build script. The build script will also update markdown files and generate external help.

Make sure to edit the markdown file(s) in the .\Docs\Help folder and populate {{ ... }} placeholders with missed help content.

Tests

Pester is the ubiquitous test and mock framework for PowerShell. We use it for automatic testing and it executes at Pull Requests. We have a lot improvements to do on the test front and contributions are more than welcome. The progress can be tracked here.

Pull Requests

If you like to start contributing to Bicep PowerShell. Please make sure that there is a related issue to link to your PR.

  • All PRs should be tagged using the labels, newFeature, bugFix, updatedDocs or enhancement. This is used for automatic release notes creation.
  • Make sure that the issue is tagged in the PR.
  • Write a short but informative commit message, it will be added to the release notes.

Feature Suggestions

  • Please first search Open 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 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 PowerShell module, PowerShell version and OS 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.