Skip to content

Commit 3dfbde8

Browse files
jamastenjamasten
committed
Added Contributors Guide
1 parent 6b5b4f8 commit 3dfbde8

8 files changed

+244
-0
lines changed

‎CONTRIBUTING.md

+15
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Contributors Guide
2+
13
This project welcomes contributions and suggestions. Most contributions require you to agree to a
24
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
35
the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
@@ -7,5 +9,18 @@ a CLA and decorate the PR appropriately (e.g., status check, comment). Simply fo
79
provided by the bot. You will only need to do this once across all repos using our CLA.
810

911
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
12+
1013
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
1114
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
15+
16+
## Update Checklist
17+
18+
When contributing to the the solution be sure to follow the checklist items below to ensure your changes adhere to the established norms:
19+
20+
1. [File Structure](./workload/docs/contributing/fileStructure.md)
21+
1. [Banners](./workload/docs/contributing/banners.md)
22+
1. [Naming Standard](./workload/docs/contributing/namingStandard.md)
23+
1. [Comments](./workload/docs/contributing/comments.md)
24+
1. [Parameters File Samples](./workload/docs/contributing/parametersFileSamples.md)
25+
1. [ARM Templates](./workload/docs/contributing/armTemplates.md)
26+
1. [Documents & Diagrams](./workload/docs/contributing/documentsDiagrams.md)

‎workload/docs/contributing/armTemplates.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Contributing Guide: ARM Templates
2+
3+
[Overview](../../../CONTRIBUTING.md) | [File Structure](fileStructure.md) | [Banners](contributing/banners.md) | [Naming Standard](namingStandard.md) | [Comments](comments.md) | [Parameters File Samples](parametersFileSamples.md) | [ARM Templates](armTemplates.md) | [Documents & Diagrams](documentsDiagrams.md)
4+
5+
When any changes have been made to a bicep file in the repository, the deploy-*.bicep for the solution must be compiled into JSON and be placed in the appropriate directory.
6+
7+
1. Install the Bicep extension in VSCode.
8+
1. Right click on the deploy-*.bicep file for solution you are adding or modifying.
9+
1. Select "Build ARM Template" from the menu.
10+
1. Move the JSON file to the "arm" folder. The file for the baseline and custom image solutions must be placed in the root. The file for a brownfield deployment must be placed in the brownfield folder.

‎workload/docs/contributing/banners.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Contributing Guide: Banners
2+
3+
[Overview](../../../CONTRIBUTING.md) | [File Structure](fileStructure.md) | [Banners](contributing/banners.md) | [Naming Standard](namingStandard.md) | [Comments](comments.md) | [Parameters File Samples](parametersFileSamples.md) | [ARM Templates](armTemplates.md) | [Documents & Diagrams](documentsDiagrams.md)
4+
5+
Each section, if specified, in your bicep files must have a banner:
6+
7+
## Parameters
8+
9+
```bash
10+
// ========== //
11+
// Parameters //
12+
// ========== //
13+
```
14+
15+
## Variables
16+
17+
```bash
18+
// =========== //
19+
// Variable declaration //
20+
// =========== //
21+
```
22+
23+
## Resources (above all modules and resources)
24+
25+
```bash
26+
// =========== //
27+
// Deployments //
28+
// =========== //
29+
```
30+
31+
## Outputs
32+
33+
```bash
34+
// =========== //
35+
// Outputs //
36+
// =========== //
37+
```

‎workload/docs/contributing/comments.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Contributing Guide: Comments
2+
3+
[Overview](../../../CONTRIBUTING.md) | [File Structure](fileStructure.md) | [Banners](contributing/banners.md) | [Naming Standard](namingStandard.md) | [Comments](comments.md) | [Parameters File Samples](parametersFileSamples.md) | [ARM Templates](armTemplates.md) | [Documents & Diagrams](documentsDiagrams.md)
4+
5+
Every module and resource in the bicep files must have a comment describing its resource and if necessary, its purpose. For example, for a resource group, the following comment would be placed above the resource:
6+
7+
```bash
8+
// Resource group.
9+
module resourceGroup '../../carml/1.3.0/Microsoft.Resources/resourceGroups/deploy.bicep' = {
10+
scope: subscription(avdWorkloadSubsId)
11+
name: 'Deploy-${varRgName}-${time}'
12+
params: {
13+
name: varRgName
14+
location: avdSessionHostLocation
15+
enableDefaultTelemetry: false
16+
tags: createResourceTags ? union(varAllComputeStorageTags, varAvdCostManagementParentResourceTag) : varAvdCostManagementParentResourceTag
17+
}
18+
dependsOn: avdDeployMonitoring ? [
19+
monitoringDiagnosticSettings
20+
] : []
21+
}
22+
```
23+
24+
Or you could provide more detail around the resource or resource group if more than one exists in the solution. For example:
25+
26+
```bash
27+
// Resource group for AVD session hosts.
28+
module resourceGroup '../../carml/1.3.0/Microsoft.Resources/resourceGroups/deploy.bicep' = {
29+
scope: subscription(avdWorkloadSubsId)
30+
name: 'Deploy-${varRgName}-${time}'
31+
params: {
32+
name: varRgName
33+
location: avdSessionHostLocation
34+
enableDefaultTelemetry: false
35+
tags: createResourceTags ? union(varAllComputeStorageTags, varAvdCostManagementParentResourceTag) : varAvdCostManagementParentResourceTag
36+
}
37+
dependsOn: avdDeployMonitoring ? [
38+
monitoringDiagnosticSettings
39+
] : []
40+
}
41+
```

‎workload/docs/contributing/documentsDiagrams.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Contributing Guide: Documents & Diagrams
2+
3+
[Overview](../../../CONTRIBUTING.md) | [File Structure](fileStructure.md) | [Banners](contributing/banners.md) | [Naming Standard](namingStandard.md) | [Comments](comments.md) | [Parameters File Samples](parametersFileSamples.md) | [ARM Templates](armTemplates.md) | [Documents & Diagrams](documentsDiagrams.md)
4+
5+
When making any changes to the baseline, ensure the following documents and diagrams are updated:
6+
7+
- workload/docs/deploy-baseline.md: add any new inputs / elements that were added to the UI definition
8+
- workload/docs/getting-started-baseline.md: add any prerequisites (similar to the infobox in the portal UI).
9+
- workload/docs/diagrams/avd-accelerator-baseline-architecture.vsdx:
10+
- Update diagram to include any new resources.
11+
- Save it as a "vsdx" and "png" to the "workload\docs\diagrams" folder.

‎workload/docs/contributing/fileStructure.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Contributors Guide: File Structure
2+
3+
[Overview](../../../CONTRIBUTING.md) | [File Structure](fileStructure.md) | [Banners](contributing/banners.md) | [Naming Standard](namingStandard.md) | [Comments](comments.md) | [Parameters File Samples](parametersFileSamples.md) | [ARM Templates](armTemplates.md) | [Documents & Diagrams](documentsDiagrams.md)
4+
5+
Depending on the contribution, specific files should either be either updated or added to follow the established heirarchy and structure.
6+
7+
## Baseline
8+
9+
- workload/arm/deploy-basline.json
10+
- workload/bicep
11+
- modules/< functionality >
12+
- .bicep (contains additional module files needed for functionality)
13+
- deploy.bicep
14+
- parameters
15+
- deploy-baseline-min-parameters-example.json
16+
- deploy-baseline-parameters-example.json
17+
- deploy-baseline.bicep
18+
- readme.md
19+
- workload/portal-ui/portal-ui-baseline.json
20+
21+
## Custom Image Build
22+
23+
- workload/arm/deploy-custom-image.json
24+
- workload/bicep
25+
- modules/< functionality >
26+
- .bicep (contains additional module files needed for functionality)
27+
- deploy.bicep
28+
- parameters
29+
- deploy-custom-image-min-parameters-example.json
30+
- deploy-custom-image-parameters-example.json
31+
- deploy-baseline.bicep
32+
- readme.md
33+
- workload/portal-ui/portal-ui-baseline.json
34+
35+
## Brownfield Deployment
36+
37+
- workload/arm/brownfield/deploy< solution >.json
38+
- workload/bicep/brownfield/< solution >
39+
- modules
40+
- parameters
41+
- < solution >.parameters.all.json
42+
- < solution >.parameters.min.json
43+
- references
44+
- deploy.bicep
45+
- readme.md
46+
- workload/portal-ui/brownfield/portalUi< solution >.json

‎workload/docs/contributing/namingStandard.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Contributing Guide: Naming Standard
2+
3+
[Overview](../../../CONTRIBUTING.md) | [File Structure](fileStructure.md) | [Banners](contributing/banners.md) | [Naming Standard](namingStandard.md) | [Comments](comments.md) | [Parameters File Samples](parametersFileSamples.md) | [ARM Templates](armTemplates.md) | [Documents & Diagrams](documentsDiagrams.md)
4+
5+
## Bicep
6+
7+
### Parameters
8+
9+
- Start with a lowercase letter.
10+
- Use camel casing for each new word in the name.
11+
12+
### Variables
13+
14+
- Start with “var”.
15+
- Use camel casing for each new word in the name.
16+
17+
### Modules
18+
19+
- Symbolic name:
20+
- Start with a lowercase letter.
21+
- Use camel casing for each new word.
22+
- Describe the collective resources that are deployed within it.
23+
24+
### Deployment Name
25+
26+
- Use normal casing.
27+
- Each word is separated by a hyphen.
28+
- Value should end with the time parameter to differentiate from other deployments.
29+
- Resources:
30+
- Use CARML modules when possible but it is not mandatory, especially when prohibitive.
31+
32+
### Symbolic Name
33+
34+
- Start with a lowercase letter.
35+
- Use camel casing for each new word.
36+
- Describe the resource that is defined within it.
37+
- Resource name: ensure the name is being captured through custom naming.
38+
39+
## Documentation
40+
41+
Update the following files with names for any new resources:
42+
43+
- workload/docs/resource-naming.md
44+
- workload/docs/diagrams/avd-accelerator-resource-organization-naming.vsdx

‎workload/docs/contributing/parametersFileSamples.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing Guide: Parameters File Samples
2+
3+
[Overview](../../../CONTRIBUTING.md) | [File Structure](fileStructure.md) | [Banners](contributing/banners.md) | [Naming Standard](namingStandard.md) | [Comments](comments.md) | [Parameters File Samples](parametersFileSamples.md) | [ARM Templates](armTemplates.md) | [Documents & Diagrams](documentsDiagrams.md)
4+
5+
Each solution in the AVD Accelerator must contain parameters file samples to ensure customers can deploy the solution using PowerShell, Azure CLI, or other tooling.
6+
7+
## Files
8+
9+
Create the files for the solution if they don’t exist
10+
11+
### Baseline
12+
13+
**Directory**: workload/bicep/parameters
14+
15+
**Files**:
16+
17+
- deploy-baseline-min-parameters-example.json
18+
- deploy-baseline-parameters-example.json
19+
20+
### Custom Image Build
21+
22+
**Directory**: workload/bicep/parameters
23+
24+
**Files**:
25+
26+
- deploy-custom-image-min-parameters-example.json
27+
- deploy-custom-image-parameters-example.json
28+
29+
### Brownfield Deployment
30+
31+
**Directory**: workload/bicep/brownfield/< solution >/parameters
32+
33+
**Files**:
34+
35+
- < solution >.parameters.all.json
36+
- < solution >.parameters.min.json
37+
38+
## Updates
39+
40+
Update the appropriate files with any new parameters.

0 commit comments

Comments
 (0)