Skip to content

Commit d20824e

Browse files
NepomucenoNepomuceno
committed
docs: add CONTRIBUTING.md and improve developer documentation
- Create comprehensive CONTRIBUTING.md explaining: - Prerequisites (Go, Terraform, Make, tflint) - Project structure and source vs generated files - How code generation works with diagram - Step-by-step guide for adding new Azure resources - Field reference for resourceDefinition.json - Running locally (Make and PowerShell) - PR guidelines and checklist - Update README.md with Development section: - Brief explanation of code generation process - File overview table showing editable vs generated files - Quick start commands - Link to CONTRIBUTING.md for details Related: #174, #177 Closes #184
1 parent a837381 commit d20824e

2 files changed

Lines changed: 322 additions & 6 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
# Contributing to terraform-azurerm-naming
2+
3+
Thank you for your interest in contributing to this project! This guide will help you understand how the project works and how to contribute effectively.
4+
5+
## Table of Contents
6+
7+
- [Prerequisites](#prerequisites)
8+
- [Project Structure](#project-structure)
9+
- [How Code Generation Works](#how-code-generation-works)
10+
- [Adding a New Azure Resource](#adding-a-new-azure-resource)
11+
- [Running Locally](#running-locally)
12+
- [Pull Request Guidelines](#pull-request-guidelines)
13+
- [Getting Help](#getting-help)
14+
15+
## Prerequisites
16+
17+
Before contributing, ensure you have the following installed:
18+
19+
| Tool | Version | Purpose |
20+
|------|---------|---------|
21+
| [Go](https://golang.org/dl/) | 1.23+ | Runs the code generator |
22+
| [Terraform](https://www.terraform.io/downloads) | 1.0+ | Validates generated files |
23+
| [Make](https://www.gnu.org/software/make/) | Any | Build automation (Linux/macOS) |
24+
| [tflint](https://github.com/terraform-linters/tflint) | Latest | Terraform linting |
25+
26+
**Optional but recommended:**
27+
- [pre-commit](https://pre-commit.com/) - Automatically runs formatting checks before commits
28+
29+
### Quick Setup
30+
31+
```bash
32+
# Clone the repository
33+
git clone https://github.com/Azure/terraform-azurerm-naming.git
34+
cd terraform-azurerm-naming
35+
36+
# Install dependencies (installs terraform, terraform-docs, tfsec, tflint via Go)
37+
make install
38+
39+
# Optional: Set up pre-commit hooks
40+
pip install pre-commit
41+
pre-commit install
42+
```
43+
44+
## Project Structure
45+
46+
```
47+
terraform-azurerm-naming/
48+
├── main.go # Go generator - reads JSON, outputs Terraform
49+
├── resourceDefinition.json # Primary resource definitions (documented in Azure)
50+
├── resourceDefinition_out_of_docs.json # Resources not in official Azure docs
51+
├── templates/
52+
│ ├── main.tmpl # Template for main.tf generation
53+
│ └── outputs.tmpl # Template for outputs.tf generation
54+
├── main.tf # [GENERATED] - Do not edit manually
55+
├── outputs.tf # [GENERATED] - Do not edit manually
56+
├── variables.tf # Module input variables (manually maintained)
57+
├── Makefile # Build automation for Linux/macOS
58+
├── make.ps1 # Build automation for Windows PowerShell
59+
└── docs/
60+
├── missing_resources.md # Resources that need to be added
61+
└── not_defined.md # Resources without naming documentation
62+
```
63+
64+
### Source Files vs Generated Files
65+
66+
| File | Type | Edit? |
67+
|------|------|-------|
68+
| `resourceDefinition.json` | Source | Yes |
69+
| `resourceDefinition_out_of_docs.json` | Source | Yes |
70+
| `templates/*.tmpl` | Source | Yes |
71+
| `main.go` | Source | Yes |
72+
| `variables.tf` | Source | Yes |
73+
| `main.tf` | **Generated** | No |
74+
| `outputs.tf` | **Generated** | No |
75+
76+
## How Code Generation Works
77+
78+
The project uses a Go-based code generator that transforms JSON resource definitions into Terraform code:
79+
80+
```
81+
┌─────────────────────────────────┐
82+
│ resourceDefinition.json │──┐
83+
│ (documented resources) │ │
84+
└─────────────────────────────────┘ │
85+
▼
86+
┌─────────────────────────────────┐ │ ┌────────────┐ ┌─────────────┐
87+
│ resourceDefinition_out_of_docs │──┴──▶│ main.go │──▶│ main.tf │
88+
│ (undocumented resources) │ │ (generator)│ │ outputs.tf │
89+
└─────────────────────────────────┘ └────────────┘ └─────────────┘
90+
▲
91+
│
92+
┌──────────┴──────────┐
93+
│ templates/main.tmpl │
94+
│ templates/outputs.tmpl│
95+
└─────────────────────┘
96+
```
97+
98+
**Process:**
99+
1. `main.go` reads both JSON definition files
100+
2. Merges and sorts all resources alphabetically
101+
3. Applies Go templates to generate Terraform locals and outputs
102+
4. Writes `main.tf` and `outputs.tf`
103+
104+
## Adding a New Azure Resource
105+
106+
### Step 1: Find the Naming Rules
107+
108+
Look up the resource's naming rules in the [Azure naming rules documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules).
109+
110+
### Step 2: Choose the Right JSON File
111+
112+
- **`resourceDefinition.json`** - Use for resources documented in Microsoft's official naming rules
113+
- **`resourceDefinition_out_of_docs.json`** - Use for resources not in official documentation
114+
115+
### Step 3: Add the Resource Definition
116+
117+
Add a new entry to the appropriate JSON file:
118+
119+
```json
120+
{
121+
"name": "my_new_resource",
122+
"length": {
123+
"min": 1,
124+
"max": 80
125+
},
126+
"regex": "^[a-zA-Z0-9-]+$",
127+
"scope": "resourceGroup",
128+
"slug": "mnr",
129+
"dashes": true
130+
}
131+
```
132+
133+
#### Field Reference
134+
135+
| Field | Type | Required | Description |
136+
|-------|------|----------|-------------|
137+
| `name` | string | Yes | Resource name matching Terraform provider (e.g., `storage_account` for `azurerm_storage_account`) |
138+
| `length.min` | integer | Yes | Minimum character length allowed |
139+
| `length.max` | integer | Yes | Maximum character length allowed |
140+
| `regex` | string | Yes | Regex pattern for valid names (note: Terraform doesn't support all regex features) |
141+
| `scope` | string | Yes | Uniqueness scope: `global`, `subscription`, `resourceGroup`, or `parent` |
142+
| `slug` | string | Yes | Short abbreviation used in generated names (e.g., `st` for storage, `rg` for resource group) |
143+
| `dashes` | boolean | Yes | Whether the resource name supports dashes/hyphens |
144+
145+
#### Scope Values
146+
147+
| Scope | Meaning |
148+
|-------|---------|
149+
| `global` | Name must be globally unique across all Azure (e.g., storage accounts) |
150+
| `subscription` | Name must be unique within the subscription |
151+
| `resourceGroup` | Name must be unique within the resource group |
152+
| `parent` | Name must be unique within the parent resource |
153+
154+
### Step 4: Generate and Validate
155+
156+
```bash
157+
# Regenerate main.tf and outputs.tf
158+
make generate
159+
160+
# Format and validate
161+
make format
162+
make validate
163+
164+
# Or run all steps at once
165+
make all
166+
```
167+
168+
### Step 5: Verify Your Changes
169+
170+
Check that:
171+
- Your resource appears in `main.tf` under the `locals.az` block
172+
- Your resource has a corresponding output in `outputs.tf`
173+
- `terraform validate` passes
174+
- `terraform fmt -check` passes
175+
176+
## Running Locally
177+
178+
### Using Make (Linux/macOS)
179+
180+
```bash
181+
# Full build: install deps, generate, format, validate
182+
make all
183+
184+
# Individual targets
185+
make install # Install required tools
186+
make generate # Run Go generator
187+
make format # Run terraform fmt
188+
make validate # Run fmt check, validate, and tflint
189+
make build # install + generate
190+
```
191+
192+
### Using PowerShell (Windows)
193+
194+
```powershell
195+
# Full build
196+
.\make.ps1 all
197+
198+
# Individual tasks
199+
.\make.ps1 install
200+
.\make.ps1 generate
201+
.\make.ps1 format
202+
.\make.ps1 validate
203+
.\make.ps1 build
204+
```
205+
206+
See [#174](https://github.com/Azure/terraform-azurerm-naming/issues/174) for PowerShell documentation.
207+
208+
### Manual Commands
209+
210+
```bash
211+
# Generate Terraform files
212+
go run main.go
213+
214+
# Format Terraform files
215+
terraform fmt
216+
217+
# Validate Terraform
218+
terraform init
219+
terraform validate
220+
```
221+
222+
## Pull Request Guidelines
223+
224+
### Before Submitting
225+
226+
1. **Run the full validation suite:**
227+
```bash
228+
make all
229+
```
230+
231+
2. **Ensure generated files are committed:**
232+
- After running `make generate`, commit both `main.tf` and `outputs.tf`
233+
- These files should always reflect the current JSON definitions
234+
235+
3. **Format your code:**
236+
- Go code: `go fmt main.go`
237+
- Terraform: `terraform fmt`
238+
- JSON: Ensure proper formatting
239+
240+
4. **Test your changes:**
241+
- Run `terraform validate` to ensure the generated code is valid
242+
- Manually verify your resource output if possible
243+
244+
### PR Checklist
245+
246+
- [ ] I've read the [Code of Conduct](CODE_OF_CONDUCT.md)
247+
- [ ] I've run `make all` (or equivalent) successfully
248+
- [ ] Generated files (`main.tf`, `outputs.tf`) are included in my commit
249+
- [ ] For new resources: I've added to the correct JSON file (`resourceDefinition.json` or `resourceDefinition_out_of_docs.json`)
250+
- [ ] For new resources: I've verified the naming rules from [Azure documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules)
251+
- [ ] My changes don't break existing functionality
252+
253+
### Commit Message Format
254+
255+
Use clear, descriptive commit messages:
256+
257+
```
258+
feat: add support for azure_container_app resource
259+
fix: correct regex pattern for storage_account
260+
docs: update contributing guidelines
261+
refactor: improve template generation logic
262+
```
263+
264+
### What Happens After Submission
265+
266+
1. GitHub Actions runs `terraform fmt -check`, `terraform init`, and `terraform validate`
267+
2. A CLA bot checks if you've signed the Contributor License Agreement
268+
3. Maintainers review your changes
269+
4. Once approved, your PR will be merged
270+
271+
## Getting Help
272+
273+
- **Questions about existing resources?** Check [docs/missing_resources.md](docs/missing_resources.md)
274+
- **Found a bug?** [Open an issue](https://github.com/Azure/terraform-azurerm-naming/issues/new)
275+
- **Need clarification?** Comment on relevant issues like [#177](https://github.com/Azure/terraform-azurerm-naming/issues/177)
276+
277+
## Code of Conduct
278+
279+
This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
280+
281+
## License
282+
283+
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

‎README.md‎

Lines changed: 39 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,17 +34,50 @@ resource "azurerm_resource_group" "example" {
3434

3535
Other advanced usages will be explained in the [Advanced usage](#advanced-usage) part of this docs.
3636

37-
## Internals
37+
## Development
3838

39-
## Prerequisites and setup
39+
This module uses **code generation** to create Terraform files from JSON resource definitions. This approach ensures consistency and makes it easy to add new Azure resources.
4040

41-
- Install [tflint](https://github.com/terraform-linters/tflint) as suitable for your OS.
41+
### How It Works
4242

43-
- Run `make install` in the root directory of the repo.
43+
```
44+
resourceDefinition.json ─────┐
45+
├──▶ main.go ──▶ main.tf + outputs.tf
46+
resourceDefinition_out_of_docs.json ──┘ (generated)
47+
```
48+
49+
1. **Resource definitions** are stored in JSON files (`resourceDefinition.json` for documented resources, `resourceDefinition_out_of_docs.json` for undocumented ones)
50+
2. **Go templates** in `templates/` define the structure of the generated Terraform code
51+
3. **`main.go`** reads the JSON files, applies the templates, and outputs `main.tf` and `outputs.tf`
52+
53+
### File Overview
54+
55+
| File | Editable? | Description |
56+
|------|-----------|-------------|
57+
| `resourceDefinition.json` | Yes | Primary resource definitions |
58+
| `resourceDefinition_out_of_docs.json` | Yes | Resources not in Azure docs |
59+
| `templates/*.tmpl` | Yes | Go templates for Terraform generation |
60+
| `main.go` | Yes | The code generator |
61+
| `variables.tf` | Yes | Module input variables |
62+
| `main.tf` | **No** | Auto-generated - do not edit |
63+
| `outputs.tf` | **No** | Auto-generated - do not edit |
4464

45-
## Modifying resources
65+
### Quick Start
4666

47-
The resources are automatically generated using `go` to change the generation please change the file on the `templates` folder. To add a new resource, including its definition in the file `resourceDefinition.json`, and it will be automatically generated when `main.go` is run.
67+
```bash
68+
# Generate Terraform files after modifying JSON
69+
make generate
70+
71+
# Format and validate
72+
make all
73+
```
74+
75+
For detailed instructions on adding resources and contributing, see **[CONTRIBUTING.md](CONTRIBUTING.md)**.
76+
77+
## Prerequisites and Setup
78+
79+
- Install [tflint](https://github.com/terraform-linters/tflint) as suitable for your OS.
80+
- Run `make install` in the root directory of the repo.
4881

4982
## Current implementation
5083

0 commit comments

Comments
 (0)