Skip to content

Commit 3e9a42d

Browse files
kristopherjturnerkristopherjturner
committed
infra: establish unified project-wide standards (issue #14)
- Replace docs/standards/ content with links to central standards - Update CONTRIBUTING.md with links to central standards - Add standards compliance checklist to PR template - Add validate-repo-structure CI workflow
1 parent 2c9323e commit 3e9a42d

7 files changed

Lines changed: 115 additions & 1684 deletions

‎.github/pull_request_template.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,11 @@ Closes #<!-- issue number -->
2626
- [ ] I have added an entry to `CHANGELOG.md` under `[Unreleased]`
2727
- [ ] My code follows the project's style guidelines in `CONTRIBUTING.md`
2828
- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
29+
30+
## Standards Compliance
31+
32+
- [ ] Follows [repo structure standard](https://azurelocal.cloud/standards/repo-structure) (required files present)
33+
- [ ] Follows [naming conventions](https://azurelocal.cloud/standards/documentation/naming-conventions) (files, variables, resources)
34+
- [ ] Uses [IIC fictional company](https://azurelocal.cloud/standards/fictional-company-policy) in all examples (never Contoso)
35+
- [ ] Config changes validated against JSON Schema (if applicable)
36+
- [ ] No hardcoded IPs, names, secrets, or environment-specific values in committed code

‎.github/workflows/validate-repo-structure.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: Validate Repo Structure
2+
on:
3+
pull_request:
4+
branches: [main]
5+
6+
jobs:
7+
check-structure:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v4
11+
12+
- name: Check required root files
13+
run: |
14+
missing=0
15+
for f in README.md CONTRIBUTING.md LICENSE CHANGELOG.md .gitignore; do
16+
if [ ! -f "$f" ]; then
17+
echo "::error::Missing required file: $f"
18+
missing=$((missing + 1))
19+
fi
20+
done
21+
if [ $missing -gt 0 ]; then
22+
echo "::error::$missing required root file(s) missing"
23+
exit 1
24+
fi
25+
echo "All required root files present"
26+
27+
- name: Check required directories
28+
run: |
29+
missing=0
30+
for d in docs .github; do
31+
if [ ! -d "$d" ]; then
32+
echo "::error::Missing required directory: $d/"
33+
missing=$((missing + 1))
34+
fi
35+
done
36+
if [ $missing -gt 0 ]; then
37+
echo "::error::$missing required directory(s) missing"
38+
exit 1
39+
fi
40+
echo "All required directories present"
41+
42+
- name: Check PR template
43+
run: |
44+
if [ ! -f ".github/PULL_REQUEST_TEMPLATE.md" ]; then
45+
echo "::error::Missing .github/PULL_REQUEST_TEMPLATE.md"
46+
exit 1
47+
fi
48+
echo "PR template found"
49+
50+
- name: Check config structure (if config dir exists)
51+
run: |
52+
if [ -d "config" ]; then
53+
missing=0
54+
if [ ! -f "config/variables.example.yml" ]; then
55+
echo "::error::Missing config/variables.example.yml"
56+
missing=$((missing + 1))
57+
fi
58+
if [ ! -f "config/schema/variables.schema.json" ]; then
59+
echo "::error::Missing config/schema/variables.schema.json"
60+
missing=$((missing + 1))
61+
fi
62+
if [ $missing -gt 0 ]; then
63+
exit 1
64+
fi
65+
echo "Config structure valid"
66+
else
67+
echo "No config/ directory — skipping config checks"
68+
fi
69+
70+
- name: Check variable reference doc (if config dir exists)
71+
run: |
72+
if [ -d "config" ]; then
73+
if [ ! -f "docs/reference/variables.md" ]; then
74+
echo "::error::Missing docs/reference/variables.md (required when config/ exists)"
75+
exit 1
76+
fi
77+
echo "Variable reference doc found"
78+
else
79+
echo "No config/ directory — skipping variable reference check"
80+
fi

‎CONTRIBUTING.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,16 @@ Examples:
7474
- Include performance baselines or comparative results when relevant
7575
- Describe your test environment and results in the PR
7676

77+
## Standards
78+
79+
This project follows the **org-wide AzureLocal standards** documented at [azurelocal.cloud/standards](https://azurelocal.cloud/standards/). Key references:
80+
81+
- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required files, directories, labels, branch naming
82+
- [Scripting Standards](https://azurelocal.cloud/standards/scripting/scripting-standards) — PowerShell conventions
83+
- [Documentation Standards](https://azurelocal.cloud/standards/documentation/documentation-standards) — Writing and formatting
84+
- [Variable Management](https://azurelocal.cloud/docs/implementation/04-variable-management-standard) — Config file patterns
85+
- [Fictional Company Policy](https://azurelocal.cloud/standards/fictional-company-policy) — Use IIC, never Contoso
86+
7787
## Code of Conduct
7888

7989
Be respectful and constructive. Keep discussions on-topic and collaborative.

‎docs/standards/badge-standards.md‎

Lines changed: 4 additions & 256 deletions
Original file line numberDiff line numberDiff line change
@@ -1,258 +1,6 @@
1-
# Badge Standards — Azure Local Load Tools
1+
# Badge Standards
22

3-
![Category: Standards](https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square)
4-
![Updated: 2026-02-16](https://img.shields.io/badge/Updated-2026--02--16-lightgrey?style=flat-square)
3+
!!! info "Moved to Central Standards"
4+
Badge standards are now maintained org-wide at the central documentation site.
55

6-
This document defines the standard badges used across all `.adoc` files in the Azure Local Load Tools repository.
7-
Badges provide at-a-glance metadata — platform, tool, status, audience, and version — rendered as shields.io image macros.
8-
9-
## Quick Navigation
10-
11-
- [Badge Syntax](#badge-syntax) — AsciiDoc syntax for rendering badges
12-
- [Badge Catalog](#badge-catalog) — Complete list of all project badges
13-
- [Badge Placement](#badge-placement-rules) — Where badges go in each document tier
14-
- [Custom Badges](#creating-custom-badges) — How to create new badges
15-
16-
---
17-
18-
## Badge Syntax
19-
20-
Badges use the shields.io static badge service rendered as AsciiDoc inline image macros:
21-
22-
```asciidoc
23-
image:https://img.shields.io/badge/{LABEL}-{VALUE}-{COLOR}?style=flat-square&logo={LOGO}[{ALT TEXT}]
24-
```
25-
26-
**URL Encoding Rules**
27-
28-
- Spaces → `%20`
29-
- Hyphens in values → `--` (double dash)
30-
- Underscores → `__` (double underscore)
31-
32-
**Style**
33-
34-
All badges in this project use `?style=flat-square` for visual consistency.
35-
36-
## Badge Catalog
37-
38-
### Platform & Project Badges
39-
40-
Used on root README and `docs/index.adoc`.
41-
42-
| Badge | AsciiDoc Syntax | Preview Text |
43-
| --- | --- | --- |
44-
| **Platform** | `image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform: Azure Local]` | Platform: Azure Local |
45-
| **PowerShell Version** | `image:https://img.shields.io/badge/PowerShell-7.2%2B-5391FE?style=flat-square&logo=powershell[PowerShell 7.2+]` | PowerShell 7.2+ |
46-
| **License** | `image:https://img.shields.io/badge/License-MIT-green?style=flat-square[License: MIT]` | License: MIT |
47-
| **Project Status** | `image:https://img.shields.io/badge/Status-Pre--Release-orange?style=flat-square[Status: Pre-Release]` | Status: Pre-Release |
48-
| **Docs Hub** | `image:https://img.shields.io/badge/Docs-index.adoc-blue?style=flat-square&logo=readthedocs[Docs]` | Docs: index.adoc |
49-
50-
### Tool Badges
51-
52-
Identify which load testing tool a document covers. Used on tool guide pages and tool-specific READMEs.
53-
54-
| Badge | AsciiDoc Syntax | Preview Text |
55-
| --- | --- | --- |
56-
| **VMFleet** | `image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet]` | Tool: VMFleet |
57-
| **fio** | `image:https://img.shields.io/badge/Tool-fio-6C3483?style=flat-square[Tool: fio]` | Tool: fio |
58-
| **iPerf3** | `image:https://img.shields.io/badge/Tool-iPerf3-1ABC9C?style=flat-square[Tool: iPerf3]` | Tool: iPerf3 |
59-
| **HammerDB** | `image:https://img.shields.io/badge/Tool-HammerDB-E74C3C?style=flat-square[Tool: HammerDB]` | Tool: HammerDB |
60-
| **stress-ng** | `image:https://img.shields.io/badge/Tool-stress--ng-F39C12?style=flat-square[Tool: stress-ng]` | Tool: stress-ng |
61-
62-
### Version Badges
63-
64-
Show the version of a tool or component. Used on tool overview pages.
65-
66-
| Badge | AsciiDoc Syntax | Preview Text |
67-
| --- | --- | --- |
68-
| **VMFleet Version** | `image:https://img.shields.io/badge/VMFleet-2.1.0.0-blue?style=flat-square[VMFleet 2.1.0.0]` | VMFleet 2.1.0.0 |
69-
| **DiskSpd Version** | `image:https://img.shields.io/badge/DiskSpd-2.2-blue?style=flat-square[DiskSpd 2.2]` | DiskSpd 2.2 |
70-
| **Ansible Version** | `image:https://img.shields.io/badge/Ansible-2.14%2B-EE0000?style=flat-square&logo=ansible[Ansible 2.14+]` | Ansible 2.14+ |
71-
72-
### Implementation Status Badges
73-
74-
Indicate whether a tool or feature is implemented. Used on tool overview pages and READMEs.
75-
76-
| Badge | AsciiDoc Syntax | Preview Text |
77-
| --- | --- | --- |
78-
| **Fully Implemented** | `image:https://img.shields.io/badge/Status-Implemented-brightgreen?style=flat-square[Status: Implemented]` | Status: Implemented |
79-
| **In Progress** | `image:https://img.shields.io/badge/Status-In%20Progress-yellow?style=flat-square[Status: In Progress]` | Status: In Progress |
80-
| **Placeholder** | `image:https://img.shields.io/badge/Status-Placeholder-lightgrey?style=flat-square[Status: Placeholder]` | Status: Placeholder |
81-
| **Deprecated** | `image:https://img.shields.io/badge/Status-Deprecated-red?style=flat-square[Status: Deprecated]` | Status: Deprecated |
82-
83-
### Document Category Badges
84-
85-
Identify the type/category of the document. Used on guide documents.
86-
87-
| Badge | AsciiDoc Syntax | Preview Text |
88-
| --- | --- | --- |
89-
| **Getting Started** | `image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started]` | Category: Getting Started |
90-
| **Tool Guide** | `image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide]` | Category: Tool Guide |
91-
| **Operations** | `image:https://img.shields.io/badge/Category-Operations-9B59B6?style=flat-square[Category: Operations]` | Category: Operations |
92-
| **Reference** | `image:https://img.shields.io/badge/Category-Reference-7F8C8D?style=flat-square[Category: Reference]` | Category: Reference |
93-
| **Standards** | `image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards]` | Category: Standards |
94-
95-
### Audience & Difficulty Badges
96-
97-
Indicate the intended audience or skill level. Used on getting-started and tool guide pages.
98-
99-
| Badge | AsciiDoc Syntax | Preview Text |
100-
| --- | --- | --- |
101-
| **Beginner** | `image:https://img.shields.io/badge/Level-Beginner-brightgreen?style=flat-square[Level: Beginner]` | Level: Beginner |
102-
| **Intermediate** | `image:https://img.shields.io/badge/Level-Intermediate-yellow?style=flat-square[Level: Intermediate]` | Level: Intermediate |
103-
| **Advanced** | `image:https://img.shields.io/badge/Level-Advanced-red?style=flat-square[Level: Advanced]` | Level: Advanced |
104-
105-
### Audience Role Badges
106-
107-
Identify the target reader role. Used on guide documents.
108-
109-
| Badge | AsciiDoc Syntax | Preview Text |
110-
| --- | --- | --- |
111-
| **Infrastructure Engineer** | `image:https://img.shields.io/badge/Audience-Infra%20Engineer-0078D4?style=flat-square[Audience: Infra Engineer]` | Audience: Infra Engineer |
112-
| **DevOps Engineer** | `image:https://img.shields.io/badge/Audience-DevOps-5C2D91?style=flat-square[Audience: DevOps]` | Audience: DevOps |
113-
| **Storage Admin** | `image:https://img.shields.io/badge/Audience-Storage%20Admin-2E86C1?style=flat-square[Audience: Storage Admin]` | Audience: Storage Admin |
114-
| **Network Engineer** | `image:https://img.shields.io/badge/Audience-Network%20Engineer-1ABC9C?style=flat-square[Audience: Network Engineer]` | Audience: Network Engineer |
115-
| **DBA** | `image:https://img.shields.io/badge/Audience-DBA-E74C3C?style=flat-square[Audience: DBA]` | Audience: DBA |
116-
117-
### OS & Environment Badges
118-
119-
Indicate required operating system or execution environment. Used on prerequisites and tool pages.
120-
121-
| Badge | AsciiDoc Syntax | Preview Text |
122-
| --- | --- | --- |
123-
| **Windows** | `image:https://img.shields.io/badge/OS-Windows-0078D6?style=flat-square&logo=windows[OS: Windows]` | OS: Windows |
124-
| **Linux** | `image:https://img.shields.io/badge/OS-Linux-FCC624?style=flat-square&logo=linux&logoColor=black[OS: Linux]` | OS: Linux |
125-
| **WSL2** | `image:https://img.shields.io/badge/OS-WSL2-FCC624?style=flat-square&logo=linux&logoColor=black[OS: WSL2]` | OS: WSL2 |
126-
127-
### CI/CD Pipeline Badges
128-
129-
Show pipeline status (link to actual workflows once created). Used on root README.
130-
131-
| Badge | AsciiDoc Syntax | Preview Text |
132-
| --- | --- | --- |
133-
| **Build Docs** | `image:https://img.shields.io/github/actions/workflow/status/AzureLocal/azurelocal-loadtools/build-docs.yml?style=flat-square&label=Docs%20Build[Docs Build]` | Docs Build: passing |
134-
| **Tests** | `image:https://img.shields.io/github/actions/workflow/status/AzureLocal/azurelocal-loadtools/run-tests.yml?style=flat-square&label=Tests[Tests]` | Tests: passing |
135-
| **Lint** | `image:https://img.shields.io/github/actions/workflow/status/AzureLocal/azurelocal-loadtools/lint.yml?style=flat-square&label=Lint[Lint]` | Lint: passing |
136-
137-
!!! note
138-
CI/CD badges use the GitHub Actions workflow status endpoint. These will show actual pass/fail status once the workflows exist.
139-
140-
### Last Updated Badge
141-
142-
Show when a document was last modified. Used on any document where freshness matters.
143-
144-
| Badge | AsciiDoc Syntax | Preview Text |
145-
| --- | --- | --- |
146-
| **Last Updated** | `image:https://img.shields.io/badge/Updated-2026--02--16-lightgrey?style=flat-square[Updated: 2026-02-16]` | Updated: 2026-02-16 |
147-
148-
!!! tip
149-
Update the date in the badge URL each time the document is modified. Use ISO 8601 format (`YYYY-MM-DD`) with double-dash escaping.
150-
151-
## Badge Placement Rules
152-
153-
### Placement by Document Tier
154-
155-
| Tier | Badge Placement |
156-
| --- | --- |
157-
| **Standards** | After all attributes, before the `[abstract]` block. One badge per line. |
158-
| **Guides** | After all attributes, before the first content paragraph. One badge per line. |
159-
| **READMEs** | After all attributes, before the first content paragraph. Badges on the same line (inline) separated by a space. |
160-
161-
### Example: Guide with Badges
162-
163-
```asciidoc
164-
= VMFleet Deployment
165-
:toc: left
166-
:toclevels: 3
167-
...
168-
169-
image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet]
170-
image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide]
171-
image:https://img.shields.io/badge/Status-Implemented-brightgreen?style=flat-square[Status: Implemented]
172-
173-
This guide covers installing the VMFleet module...
174-
```
175-
176-
### Example: Standards with Badges
177-
178-
```asciidoc
179-
= Document Title — Subtitle
180-
Kristopher Turner
181-
v1.0, 2026-02-16
182-
183-
:description: ...
184-
:toc: left
185-
...
186-
187-
image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards]
188-
189-
[abstract]
190-
One to three sentences.
191-
```
192-
193-
### Example: README with Badges
194-
195-
```asciidoc
196-
= Azure Local Load Tools
197-
:toc: macro
198-
:toclevels: 2
199-
:icons: font
200-
201-
image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform] image:https://img.shields.io/badge/PowerShell-7.2%2B-5391FE?style=flat-square&logo=powershell[PowerShell] image:https://img.shields.io/badge/License-MIT-green?style=flat-square[License]
202-
203-
Comprehensive load testing framework...
204-
205-
toc::[]
206-
```
207-
208-
!!! note
209-
In READMEs, placing badges on the same line (separated by spaces) renders them as an inline row. In guides and standards, one badge per line stacks vertically.
210-
211-
### Required Badges by Location
212-
213-
| Document | Required Badges |
214-
| --- | --- |
215-
| Root `README.adoc` | Platform, PowerShell Version, License, Project Status |
216-
| `docs/index.adoc` | Platform, Project Status |
217-
| `docs/getting-started/*.adoc` | Category (Getting Started) |
218-
| `docs/tools/{tool}/overview.adoc` | Tool, Status (Implemented/Placeholder), Version (if applicable) |
219-
| `docs/tools/{tool}/*.adoc` (other) | Tool, Category (Tool Guide) |
220-
| `docs/operations/*.adoc` | Category (Operations) |
221-
| `docs/reference/*.adoc` | Category (Reference) |
222-
| `docs/standards/*.adoc` | Category (Standards) |
223-
| `src/solutions/*/README.md` | Tool, Status |
224-
225-
!!! tip
226-
Audience, Level, OS, and Last Updated badges are **optional** — add them when they provide meaningful context.
227-
228-
## Creating Custom Badges
229-
230-
To create a new badge not listed in the catalog:
231-
232-
1. Go to [https://shields.io/badges/static-badge](https://shields.io/badges/static-badge)
233-
2. Set the label, value, and color
234-
3. Always use `?style=flat-square` for consistency
235-
4. Add `&logo={logo-name}` if an appropriate [Simple Icons](https://simpleicons.org) logo exists
236-
5. Add the new badge to this standards document before using it in other files
237-
238-
### Color Palette
239-
240-
Use these colors for consistency across the project:
241-
242-
| Color | Hex | Usage |
243-
| --- | --- | --- |
244-
| `0078D4` | Microsoft Blue | Platform, Azure-related, VMFleet |
245-
| `5391FE` | PowerShell Blue | PowerShell version |
246-
| `brightgreen` | (shields default) | Implemented, Beginner, positive status |
247-
| `green` | (shields default) | License, Getting Started category |
248-
| `yellow` | (shields default) | In Progress, Intermediate |
249-
| `orange` | (shields default) | Pre-Release, Standards category |
250-
| `red` | (shields default) | Deprecated, Advanced |
251-
| `lightgrey` | (shields default) | Placeholder, Last Updated, neutral |
252-
| `6C3483` | Purple | fio tool |
253-
| `1ABC9C` | Teal | iPerf3 tool, Network Engineer |
254-
| `E74C3C` | Red | HammerDB tool, DBA |
255-
| `F39C12` | Amber | stress-ng tool |
256-
| `3498DB` | Blue | Tool Guide category |
257-
| `9B59B6` | Violet | Operations category |
258-
| `7F8C8D` | Grey | Reference category |
6+
**Canonical reference:** [Badge Library](https://azurelocal.cloud/standards/documentation/badge-library)

0 commit comments

Comments
 (0)