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.
Help us keep this project open and inclusive. Please read and follow our Code of Conduct.
If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to the GitHub Repository. Even better, you can submit a Pull Request with a fix.
You can request a new feature by submitting an issue to the GitHub Repository. If you would like to implement a new feature, please submit an issue with a proposal for your work first, to be sure that we can use it.
- Small Features can be crafted and directly submitted as a Pull Request.
The Azure resource group should adhere to the following naming pattern: rg-{workload/recipe}-{optional-info}.
Azure resources within the resource group should should adhere to the following naming pattern: {resource-type}-{unique-value}-{optional-info}.
Each segment is defined as follows:
- resource-type: should be one of the resource abbreviations specified in the Microsoft Cloud Adoption Framework (CAF) resource abbreviations list.
- workload/app: should specify a lowercase short name for the recipe, using "rcp" as an abbreviation for recipe. For example:
- funcevhrcp
- funchttprcp
- webapimrcp
- unique-value: should be a unique value scoped to the parent resource group. The value should be no more than 13 characters in length.
- optional info: should include optional information which may useful in identifying the resource's purpose. For example:
- 001 (index when there are multilpe resource types of the same general name)
- bastion (to help indicate the resource is related to Azure Bastion)
- tf (to indicate a Terraform-based deployment)
- bcp (to indicate a Bicep-based deployment)
Various linting tools & processes are in place to help ensure consistency of documentation and source code.
If you use VS Code as your preferred editor, please install the markdownlint extension and ensure that all rules are followed. This will help ensure consistency in the look and feel of the documentation in this repo.
Additionally, you can run the markdown linting from the command line:
npm install
npm run lintIf there is a linting error, you'll notice output similar to the following:
> markdownlint "**/*.md" --ignore node_modules
> markdownlint "**/*.md" --ignore node_modules
CHANGELOG.md:3:1 MD033/no-inline-html Inline HTML [Element: a]
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @ lint: `markdownlint "**/*.md" --ignore node_modules`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the @ lint script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
npm ERR! A complete log of this run can be found in:
npm ERR! /home/vscode/.npm/_logs/2022-10-04T19_44_18_330Z-debug.logResolve the error(s) and run the linter again to ensure a clean output.
The markdown-link-check package can be used to validate the links in Markdown files. The following command can be used:
find . -name \*.md ! -path "./node_modules/*" -exec markdown-link-check --verbose --config link-check-config.json {} \;The above command will find all Markdown (.md) files that are not in the node_modules folder, passing each file to the markdown-link-check package. The link-check-config.json file is used to set configuration values for checking the links.
Bash shell scripts should adhere to linting rules defined in shellcheck.
Bash shell scripts are expected to follow Google's Bash Style Guide.
Developers can use the ShellCheck extension in VS Code to get a local linting experience. The extension requires shellcheck to be installed. There are many options to install shellcheck; choose the option best for your local development environment.
For more information, please refer to the CSE Code with Engineering playbook recipe for Bash Code Reviews.
Running shellcheck against an invalid .sh file will show an error where the lint check failed.
shellcheck test.sh
In test.sh line 1:
^-- SC2148: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.
For more information:
https://www.shellcheck.net/wiki/SC2148 -- Tips depend on target shell and y...It is possible to run a linting process against Azure Bicep files as of Azure Bicep v0.4. The liniting process is automatic in the execution of the az bicep build command.
Additionally, the Azure Bicep extension for Visual Studio Code will perform real-time linting when editing .bicep files.
Azure Bicep linting rules are configured via the bicepconfig.json file.
To learn more about Azure Bicep linting, please refer to documentation on using the Bicep linter.
Terraform scripts should adhere to linting rules defined by TFLint. Rules for the Terraform language are built into the TFLint binary, so you don't need to install any plugins for enforcing best practices, naming conventions, warn about deprecated syntax, unused declarations, etc. The terraform version is currently set to be 0.15.4 and the TFLint version is set to be 0.28.1 in the terraform linting Azure DevOPs pipeline.
Follow the link here to install Terraform.
Running tflint locally will require you to install TFLint; using the option best for your local development environment and then running the below commands:
# Rewrite Terraform configuration files to a canonical format and style.
# If this fails use 'terraform fmt -recursive' command to resolve
terraform fmt -recursive -diff -check
# Apply linting rules
tflint
# Initialize working directory containing Terraform configuration files
terraform init
# Validate the configuration files in the directory
terraform validateThe details for the terraform fmt, terraform init and terraform validate commands can be found in the respective links.
Developers can use the Hashicorp Terraform Visual Studio Code extension in VS Code to get a local linting experience. The VSCode Azure Terraform extension in VS Code provides terraform command support for Azure.
For more information, please refer to the CSE Code with Engineering playbook recipe for Terraform Code Reviews.
Running tflint against an invalid .tf file will show an error where the lint check failed.
tflint
modules/resource-group/main.tf
--- old/modules/resource-group/main.tf
+++ new/modules/resource-group/main.tf
@@ -1,4 +1,4 @@
resource "azurerm_resource_group" "example" {
- name = "example"
+ name = "example"
location = "West US"
}
\ No newline at end of fileCode-related assets (application source code, scripts, infrastructure-as-code, related README files, etc.) should be placed within the following folder hierarchy.
\.azuredevops (Azure DevOps pull request template(s) and YAML pipelines)
\pipelines
\templates
\variables
\.devcontainer (Visual Studio Code dev container)
\.vscode
\docs (documentation that applies to the overall project)
\scripts (utility scripts for builds)
\src
\common
\app_code
\app1 (function app, web app, etc.)
\src (code for the app)
\app2
\src
\infrastructure
\bicep
\modules
\network
main.bicep
\storage
main.bicep
\terraform
\modules
\network
main.tf
\storage
main.tf
\recipe-1
\.vscode
\deploy
\terraform
\foo (module that isn't applicable to other recipes)
foo.tf
main.tf (reference modules in the \src\common\infrastructure\terraform\modules directory)
\bicep
main.bicep (references modules in the \src\common\infrastructure\bicep\modules directory)
\scripts (.ps1, .sh, etc. scripts to use the recipe)
\docs (documentation specific to a recipe)
README.md (initial content describing the recipe)
\recipe-2
Before you submit an issue, search the archive, maybe your question was already answered.
If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues. Providing the following information will increase the chances of your issue being dealt with quickly:
- Overview of the Issue - if an error is being thrown a non-minified stack trace helps
- Version - what version is affected (e.g. 0.1.2)
- Motivation for or Use Case - explain what are you trying to do and why the current behavior is a bug for you
- Browsers and Operating System - is this a problem with all browsers?
- Reproduce the Error - provide a live example or a unambiguous set of steps
- Related Issues - has a similar issue been reported before?
- Suggest a Fix - if you can't fix the bug yourself, perhaps you can point to what might be causing the problem (line of code or commit)
You can file new issues by providing the above information at the corresponding repository's issues link: https://github.com/Azure-Samples/virtual-network-integration-recipes/issues/new.
Before you submit your Pull Request (PR) consider the following guidelines:
-
Search the repository for an open or closed PR that relates to your submission. You don't want to duplicate effort.
-
Make your changes in a new git fork:
-
Commit your changes using a descriptive commit message
-
Push your fork to GitHub:
-
In GitHub, create a pull request
-
If we suggest changes then:
-
Make the required updates.
-
Rebase your fork and force push to your GitHub repository (this will update your Pull Request):
git rebase master -i git push -f
-
That's it! Thank you for your contribution!