zhongwei/gh-basher83-lunar-claude-plugins-infrastructure-ansible-best-practices
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:00:24 +08:00
commit 4768fb755a
22 changed files with 11534 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

986
skills/ansible-best-practices/patterns/documentation-templates.md Normal file
View File

@@ -0,0 +1,986 @@
# Documentation Templates
## Summary: Pattern Confidence
Analyzed 7 geerlingguy roles: security, users, docker, postgresql, nginx, pip, git
**Universal Patterns (All 7 roles):**
- Consistent README structure: Title + Badge → Description → Requirements → Variables → Dependencies → Example →
License → Author (7/7 roles)
- CI badge showing test status with link to workflow (7/7 roles)
- Code-formatted variable defaults with detailed descriptions (7/7 roles)
- Example playbook section with working examples (7/7 roles)
- Inline code formatting for variables, file paths, commands (7/7 roles)
- Explicit "None" for empty sections (Requirements, Dependencies) (7/7 roles)
- License + Author sections with links (7/7 roles)
- Variable grouping for related configuration (7/7 roles)
- Commented list examples showing optional items (7/7 roles)
**Contextual Patterns (Varies by complexity):**
- Warning/caveat sections: security-critical roles have prominent warnings, simple roles don't need them
- Variable documentation depth: complex roles (postgresql) have extensive inline docs, simple roles (pip) are
more concise
- Example complexity: simple roles show basic examples, complex roles show multiple scenarios
- Troubleshooting sections: recommended for roles that modify critical services (SSH, networking), optional for
simple roles
- Complex variable documentation: roles with 5+ optional dict attributes show ALL keys with inline comments
**Evolving Patterns (Newer roles improved):**
- PostgreSQL shows best practices for complex variable documentation: show all keys, mark required vs optional,
document defaults
- nginx demonstrates template extensibility documentation (Jinja2 block inheritance)
- Complex roles provide comprehensive inline examples in defaults/ files as primary documentation
**Sources:**
- geerlingguy.security (analyzed 2025-10-23)
- geerlingguy.github-users (analyzed 2025-10-23)
- geerlingguy.docker (analyzed 2025-10-23)
- geerlingguy.postgresql (analyzed 2025-10-23)
- geerlingguy.nginx (analyzed 2025-10-23)
- geerlingguy.pip (analyzed 2025-10-23)
- geerlingguy.git (analyzed 2025-10-23)
**Repositories:**
- <https://github.com/geerlingguy/ansible-role-security>
- <https://github.com/geerlingguy/ansible-role-github-users>
- <https://github.com/geerlingguy/ansible-role-docker>
- <https://github.com/geerlingguy/ansible-role-postgresql>
- <https://github.com/geerlingguy/ansible-role-nginx>
- <https://github.com/geerlingguy/ansible-role-pip>
- <https://github.com/geerlingguy/ansible-role-git>
## Pattern Confidence Levels (Historical)
Analyzed 2 geerlingguy roles: security, github-users
**Universal Patterns (Both roles use identical approach):**
1. ✅ **README structure** - Both follow: Title + Badge → Description → Requirements → Variables → Dependencies →
Example → License → Author
2. ✅ **CI badge** - Both include GitHub Actions CI badge with link to workflow
3. ✅ **Variable documentation format** - Code-formatted default + detailed description
4. ✅ **Example playbook section** - Both show minimal working example with vars
5. ✅ **Inline code formatting** - Backticks for variables, file paths, commands
6. ✅ **Commented list examples** - Show example list items as comments
7. ✅ **"None" for empty sections** - Explicit "None" instead of omitting (Requirements, Dependencies)
8. ✅ **License + Author sections** - Both include MIT license and author with links
9. ✅ **Variable grouping** - Related variables documented together with shared context
**Contextual Patterns (Varies by role complexity):**
1. ⚠️ **Warning/caveat section** - security has prominent security warning, github-users doesn't need
one
2. ⚠️ **Variable detail level** - security has extensive variable docs with warnings, github-users is more
concise (fewer variables)
3. ⚠️ **Example complexity** - security shows vars_files pattern, github-users shows inline vars (simpler)
4. ⚠️ **Troubleshooting section** - Neither role has explicit troubleshooting (could be added)
**Key Finding:** README documentation follows a strict template across roles. Only the caveat/warning section varies
based on role risk profile.
## Overview
This document captures documentation patterns from production-grade Ansible roles, demonstrating how to create
clear, comprehensive README files that help users understand and use the role effectively.
## README Structure
### Pattern: Comprehensive README Template
**Description:** A well-structured README that follows a consistent format, providing all necessary information for
users to understand and use the role.
**File Path:** `README.md`
**Standard README Sections:**
1. Title and badges
2. Caveat/Warning (if applicable)
3. Role description
4. Requirements
5. Role Variables
6. Dependencies
7. Example Playbook
8. License
9. Author Information
### Section 1: Title and Badges
**Example Code:**
```markdown
# Ansible Role: Security (Basics)
[![CI](https://github.com/geerlingguy/ansible-role-security/actions/workflows/ci.yml/badge.svg)](https://github.com/geerlingguy/ansible-role-security/actions/workflows/ci.yml)
```
**Key Elements:**
1. **Clear title** - Role name with descriptive subtitle
2. **CI badge** - Shows test status (builds confidence)
3. **Badge links to CI** - Users can see test results
**When to Use:**
- Always include clear role title
- Add CI badge if you have automated testing
- Link badges to their status pages
- Consider adding Galaxy badge, version badge, downloads badge
**Badge Examples:**
```markdown
[![CI](https://github.com/user/repo/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions)
[![Ansible Galaxy](https://img.shields.io/badge/galaxy-user.rolename-blue.svg)](https://galaxy.ansible.com/user/rolename)
[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
```
**Anti-pattern:**
- Don't skip the title (obvious but happens)
- Avoid outdated or broken badges
- Don't add badges that don't provide value
### Section 2: Caveat/Warning (Optional)
**Example Code:**
```markdown
**First, a major, MAJOR caveat**: the security of your servers is YOUR
responsibility. If you think simply including this role and adding a firewall
makes a server secure, then you're mistaken. Read up on Linux, network, and
application security, and know that no matter how much you know, you can
always make every part of your stack more secure.
That being said, this role performs some basic security configuration on
RedHat and Debian-based linux systems. It attempts to:
- Install software to monitor bad SSH access (fail2ban)
- Configure SSH to be more secure (disabling root login, requiring
key-based authentication, and allowing a custom SSH port to be set)
- Set up automatic updates (if configured to do so)
There are a few other things you may or may not want to do (which are not
included in this role) to make sure your servers are more secure, like:
- Use logwatch or a centralized logging server to analyze and monitor
log files
- Securely configure user accounts and SSH keys (this role assumes you're
not using password authentication or logging in as root)
- Have a well-configured firewall (check out the `geerlingguy.firewall`
role on Ansible Galaxy for a flexible example)
Again: Your servers' security is *your* responsibility.
```
**Key Elements:**
1. **Prominent warning** - Sets expectations clearly
2. **Scope definition** - What the role does and doesn't do
3. **Additional recommendations** - Points to complementary practices
4. **Emphasis** - Bold, italics, repetition for important points
**When to Use:**
- Security-related roles (critical warnings)
- Roles that could cause service disruption
- Roles with common misunderstandings
- Complex roles with limited scope
**Anti-pattern:**
- Don't add warnings for routine roles
- Avoid legal disclaimers (that's what LICENSE is for)
- Don't be condescending
### Section 3: Requirements
**Example Code:**
```markdown
## Requirements
For obvious reasons, `sudo` must be installed if you want to manage the
sudoers file with this role.
On RedHat/CentOS systems, make sure you have the EPEL repository installed
(you can include the `geerlingguy.repo-epel` role to get it installed).
No special requirements for Debian/Ubuntu systems.
```
**Key Elements:**
1. **System requirements** - Software that must be pre-installed
2. **OS-specific requirements** - Different requirements per platform
3. **How to meet requirements** - Links to other roles or instructions
4. **Explicit "no requirements" statement** - Clarity when none exist
**When to Use:**
- List any software that must be installed first
- Document repository requirements (EPEL, PPAs)
- Mention privilege requirements (become/sudo)
- Note Python library dependencies
- State "None" if no requirements (clear communication)
**Anti-pattern:**
- Don't assume users know about EPEL or special repos
- Avoid listing Ansible itself (assumed)
- Don't skip this section (at least say "None")
### Section 4: Role Variables
**Example Code:**
```markdown
## Role Variables
Available variables are listed below, along with default values (see
`defaults/main.yml`):
security_ssh_port: 22
The port through which you'd like SSH to be accessible. The default is port
22, but if you're operating a server on the open internet, and have no
firewall blocking access to port 22, you'll quickly find that thousands of
login attempts per day are not uncommon. You can change the port to a
nonstandard port (e.g. 2849) if you want to avoid these thousands of
automated penetration attempts.
security_ssh_password_authentication: "no"
security_ssh_permit_root_login: "no"
security_ssh_usedns: "no"
security_ssh_permit_empty_password: "no"
security_ssh_challenge_response_auth: "no"
security_ssh_gss_api_authentication: "no"
security_ssh_x11_forwarding: "no"
Security settings for SSH authentication. It's best to leave these set to
`"no"`, but there are times (especially during initial server configuration
or when you don't have key-based authentication in place) when one or all
may be safely set to `'yes'`. **NOTE: It is _very_ important that you quote
the 'yes' or 'no' values. Failure to do so may lock you out of your server.**
security_ssh_allowed_users: []
# - alice
# - bob
# - charlie
A list of users allowed to connect to the host over SSH. If no user is
defined in the list, the task will be skipped.
security_sudoers_passwordless: []
security_sudoers_passworded: []
A list of users who should be added to the sudoers file so they can run any
command as root (via `sudo`) either without a password or requiring a
password for each command, respectively.
security_autoupdate_enabled: true
Whether to install/enable `yum-cron` (RedHat-based systems) or
`unattended-upgrades` (Debian-based systems). System restarts will not
happen automatically in any case, and automatic upgrades are no excuse for
sloppy patch and package management, but automatic updates can be helpful
as yet another security measure.
security_fail2ban_enabled: true
Whether to install/enable `fail2ban`. You might not want to use fail2ban if
you're already using some other service for login and intrusion detection
(e.g. [ConfigServer](http://configserver.com/cp/csf.html)).
```
**Documentation Pattern:**
For each variable:
1. **Show default value** - Code-formatted with actual default
2. **Description** - What it does, when to use it
3. **Context** - Why you might change it
4. **Examples** - Show different values for lists/dicts
5. **Warnings** - Important notes (quoting, locking out, etc.)
**Formatting Guidelines:**
- Use 4-space indentation for default values
- Group related variables together
- Add blank lines between variable groups
- Use inline code formatting for values
- Bold important warnings
- Comment out example list items
**When to Use:**
- Document ALL variables from defaults/main.yml
- Group related variables (ssh_*, autoupdate_*, etc.)
- Provide context, not just description
- Include warnings for dangerous settings
- Show example values for complex structures
**Anti-pattern:**
- Don't just list variables without explanation
- Avoid documenting vars/ (internal implementation)
- Don't skip context (users need to know WHY)
- Avoid stale documentation (keep in sync with defaults/)
### Pattern: Variable Table Format (Alternative)
**Description:** Some roles use a table format for variable documentation. While geerlingguy.security doesn't use
this, it's a valid alternative pattern.
**Example Table Format:**
```markdown
## Role Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `security_ssh_port` | `22` | SSH port number |
| `security_ssh_password_authentication` | `"no"` | Enable password authentication |
| `security_fail2ban_enabled` | `true` | Install and configure fail2ban |
```
**When to Use:**
- Roles with many simple variables
- When brief descriptions are sufficient
- For quick reference guides
**Comparison:**
| Format | Best For | Pros | Cons |
|--------|----------|------|------|
| Text with examples | Complex variables, detailed context | Detailed explanations, examples | More verbose |
| Table | Simple variables, quick reference | Concise, scannable | Limited detail space |
**Virgo-Core Preference:**
Use text format with examples (matches geerlingguy pattern) for main documentation, optionally add table for quick
reference.
### Section 5: Dependencies
**Example Code:**
```markdown
## Dependencies
None.
```
**When Dependencies Exist:**
```markdown
## Dependencies
This role depends on:
- `geerlingguy.repo-epel` (for RedHat/CentOS systems)
- `geerlingguy.firewall` (recommended but optional)
The role will automatically install required dependencies from Ansible Galaxy.
```
**Key Elements:**
1. **Explicit "None"** - Clear when no dependencies
2. **List dependencies** - With context about why needed
3. **Distinguish required vs optional** - Important for users
4. **Note automatic installation** - Reduces confusion
**When to Use:**
- Always include this section
- List role dependencies from meta/main.yml
- Note recommended complementary roles
- State "None" if no dependencies
**Anti-pattern:**
- Don't skip this section
- Avoid listing collection dependencies here (put in Requirements)
### Section 6: Example Playbook
**Example Code:**
```markdown
## Example Playbook
- hosts: servers
vars_files:
- vars/main.yml
roles:
- geerlingguy.security
*Inside `vars/main.yml`*:
security_sudoers_passworded:
- johndoe
- deployacct
```
**Key Elements:**
1. **Minimal working example** - Shows basic usage
2. **Variable override example** - Demonstrates customization
3. **Multiple files** - Shows playbook and vars file
4. **Real-world example** - Not generic foo/bar examples
5. **Indentation** - 4 spaces for YAML, maintains readability
**Enhanced Example Pattern:**
```markdown
## Example Playbook
### Basic Usage
- hosts: all
roles:
- geerlingguy.security
### Custom Configuration
- hosts: webservers
vars:
security_ssh_port: 2222
security_fail2ban_enabled: true
security_autoupdate_enabled: true
roles:
- geerlingguy.security
### Advanced Example with Sudoers
- hosts: appservers
vars:
security_sudoers_passwordless:
- deploy
security_sudoers_passworded:
- developer
- operator
roles:
- geerlingguy.security
```
**When to Use:**
- Always include at least one example
- Show basic usage first
- Add advanced examples for complex features
- Use realistic variable values
- Include multiple scenarios if role has distinct use cases
**Anti-pattern:**
- Don't use only generic examples (foo, bar, example.com)
- Avoid incomplete examples (missing required vars)
- Don't show every possible variable (overwhelming)
### Section 7: License and Author
**Example Code:**
```markdown
## License
MIT (Expat) / BSD
## Author Information
This role was created in 2014 by [Jeff Geerling](https://www.jeffgeerling.com/),
author of [Ansible for DevOps](https://www.ansiblefordevops.com/).
```
**Key Elements:**
1. **License name** - Clear license statement
2. **Author information** - Who created/maintains it
3. **Links** - Author website, book, company
4. **Year created** - Provides context
**When to Use:**
- Always include license (required for Galaxy)
- Add author name and contact
- Link to LICENSE file for full text
- Keep it brief
**Anti-pattern:**
- Don't include full license text in README (use LICENSE file)
- Avoid complex author information
## Additional Documentation Patterns
### Pattern: Troubleshooting Section
**Description:** While geerlingguy.security doesn't include a troubleshooting section, more complex roles should
include one.
**Example Troubleshooting Section:**
```markdown
## Troubleshooting
### SSH Connection Refused After Running Role
If you lose SSH connectivity after running this role, you may have:
1. Changed the SSH port without updating your firewall rules
2. Disabled password authentication without setting up SSH keys
3. Set `security_ssh_allowed_users` without including your username
**Solution:** Access the server via console and check `/etc/ssh/sshd_config`.
### Fail2ban Not Starting
If fail2ban fails to start, check that the log files it monitors exist:
ls -la /var/log/auth.log
On some minimal systems, these log files may not exist until a service
writes to them.
**Solution:** Create empty log files or disable fail2ban temporarily.
```
**When to Use:**
- Roles that modify critical services (SSH, networking)
- Roles with common configuration mistakes
- Roles with tricky OS-specific issues
- Complex roles with multiple failure modes
**Anti-pattern:**
- Don't include troubleshooting for roles that are straightforward
- Avoid listing every possible error (focus on common issues)
### Pattern: Inline Code and Formatting
**Formatting Patterns from README:**
1. **Inline code** - Use backticks: `fail2ban`, `sudo`, `/etc/ssh/sshd_config`
2. **File paths** - Always use inline code: `defaults/main.yml`
3. **Commands** - Inline code for short commands: `sudo systemctl restart ssh`
4. **Variable names** - Inline code: `security_ssh_port`
5. **Code blocks** - Use 4-space indentation for YAML/code examples
6. **Emphasis** - Bold for **important warnings**, italics for *emphasis*
7. **Lists** - Use `-` for unordered, numbers for ordered
**Example:**
```markdown
To configure SSH port, set `security_ssh_port` in your playbook variables.
The configuration is written to `/etc/ssh/sshd_config` and validated with
`sshd -T -f %s` before applying. **WARNING**: Changing the SSH port without
updating firewall rules will lock you out.
```
## Comparison to Virgo-Core Roles
### system_user Role
**README Analysis:**
**Matches:**
- ✅ Has clear title
- ✅ Good role description
- ✅ Documents variables
- ✅ Includes example playbook
- ✅ Has license and author sections
**Gaps:**
- ❌ No CI badge (no CI yet)
- ⚠️ Variable documentation less detailed (could add more context)
- ⚠️ Could add troubleshooting section (SSH key issues common)
- ⚠️ No table of contents (nice-to-have for longer docs)
**Priority Actions:**
1. **Important:** Enhance variable documentation with usage context (30 min)
2. **Important:** Add troubleshooting section (1 hour)
3. **Nice-to-have:** Add CI badge after implementing CI (5 min)
### proxmox_access Role
**README Analysis:**
**Matches:**
- ✅ Comprehensive variable documentation
- ✅ Good examples
- ✅ Security warnings included
**Gaps:**
- ❌ No CI badge
- ⚠️ Could add more example playbooks (different scenarios)
- ⚠️ Troubleshooting section would help (token creation failures)
**Priority Actions:**
1. **Important:** Add troubleshooting for common token issues (1 hour)
2. **Important:** Add more example scenarios (30 min)
3. **Nice-to-have:** Add requirements section (15 min)
### proxmox_network Role
**README Analysis:**
**Matches:**
- ✅ Good structure
- ✅ Clear variable documentation
- ✅ Network architecture context
**Gaps:**
- ❌ No CI badge
- ⚠️ Network troubleshooting section would be valuable
- ⚠️ Could add verification examples (how to check it worked)
**Priority Actions:**
1. **Important:** Add network troubleshooting section (1 hour)
2. **Important:** Add verification examples (30 min)
3. **Nice-to-have:** Add network topology diagram (1 hour)
## Template: Complete README Structure
```markdown
# Ansible Role: [Role Name]
[![CI](badge-url)](ci-url)
[![Ansible Galaxy](badge-url)](galaxy-url)
[Brief role description - what it does, key features]
[Optional: Warning/caveat section for critical roles]
## Requirements
[List prerequisites, or "None"]
## Role Variables
Available variables are listed below, along with default values (see
`defaults/main.yml`):
variable_name: default_value
[Description of variable, when to change it, usage examples]
another_variable: []
# - example1
# - example2
[Description with examples]
## Dependencies
[List role dependencies, or "None"]
## Example Playbook
### Basic Usage
- hosts: all
roles:
- rolename
### Custom Configuration
- hosts: servers
vars:
variable_name: custom_value
roles:
- rolename
## Troubleshooting
[Optional: Common issues and solutions]
## License
MIT / BSD / Apache 2.0
## Author Information
This role was created by [Author Name](link), [additional context].
```
## Validation: geerlingguy.postgresql
**Analysis Date:** 2025-10-23
**Repository:** <https://github.com/geerlingguy/ansible-role-postgresql>
### README Structure
- **Pattern: Comprehensive README template** - ✅ **Confirmed**
- PostgreSQL follows same structure: Title + Badge → Description → Requirements → Variables → Dependencies →
Example → License → Author
- **4/4 roles follow identical README structure**
### Variable Documentation
- **Pattern: Code-formatted default + detailed description** - ✅ **EXCELLENT EXAMPLE**
- PostgreSQL has extensive variable docs (50+ variables documented)
- Each variable group includes:
- Code block with default value
- Detailed description of purpose
- Usage context and examples
- Inline comments for complex structures
- **Example quality:**
```markdown
postgresql_databases:
- name: exampledb # required; the rest are optional
lc_collate: # defaults to 'en_US.UTF-8'
lc_ctype: # defaults to 'en_US.UTF-8'
encoding: # defaults to 'UTF-8'
```
- **Validates:** Complex dict variables need inline comment documentation
- **4/4 roles use this documentation pattern**
### CI Badge
- **Pattern: GitHub Actions CI badge** - ✅ **Confirmed**
- PostgreSQL includes CI badge with link to workflow
- **4/4 roles have CI badges**
### Example Playbook
- **Pattern: Basic + vars_files example** - ✅ **Confirmed**
- Shows minimal playbook + vars file pattern
- Includes example variable values for databases and users
- **4/4 roles provide working examples**
### Requirements Section
- **Pattern: Explicit requirements or "None"** - ✅ **Confirmed**
- PostgreSQL states: "No special requirements"
- Mentions become: yes requirement
- **4/4 roles include Requirements section (even if "None")**
### Dependencies Section
- **Pattern: Explicit "None"** - ✅ **Confirmed**
- PostgreSQL states: "None."
- **4/4 roles include Dependencies section**
### Advanced Pattern: Complex Variable Tables
- **Pattern Evolution:** PostgreSQL uses structured tables for complex options:
- **hba_entries:** Lists all available keys with descriptions
- **databases:** Shows optional attributes with defaults
- **users:** Documents every possible parameter
- **Insight:** When variables have 5+ optional attributes, use structured documentation
- **Recommendation:** For complex dict structures, show all keys even if optional
### Documentation for Complex Structures
- **Pattern: Show all keys, even optional** - ✅ **NEW INSIGHT**
- PostgreSQL documents every possible key for postgresql_databases, postgresql_users, postgresql_privs
- Includes comments like "# required" vs "# optional"
- Shows default values inline: `# defaults to 'en_US.UTF-8'`
- **Best practice:** Comprehensive documentation prevents user confusion
### Key Validation Findings
**What PostgreSQL Role Confirms:**
1. ✅ README structure is universal (4/4 roles identical)
2. ✅ Variable documentation format is universal (4/4 roles)
3. ✅ CI badges are universal (4/4 roles)
4. ✅ Example playbooks are universal (4/4 roles)
5. ✅ Explicit "None" for empty sections is universal (4/4 roles)
6. ✅ Inline code formatting is universal (4/4 roles)
**What PostgreSQL Role Demonstrates:**
1. 🔄 Complex variables need extensive inline documentation
2. 🔄 Show ALL available keys for dict structures, even optional ones
3. 🔄 Use comments to indicate required vs optional vs defaults
4. 🔄 Large variable sets (20+) benefit from grouping in documentation
**Pattern Confidence After PostgreSQL Validation (4/4 roles):**
- **README structure:** UNIVERSAL (4/4 roles identical)
- **Variable documentation:** UNIVERSAL (4/4 use same format)
- **CI badges:** UNIVERSAL (4/4 roles have them)
- **Example playbooks:** UNIVERSAL (4/4 provide examples)
- **Explicit "None":** UNIVERSAL (4/4 use it)
- **Complex variable docs:** VALIDATED (postgresql shows best practices for complexity)
## Validation: geerlingguy.pip
**Analysis Date:** 2025-10-23
**Repository:** <https://github.com/geerlingguy/ansible-role-pip>
### README Structure
- **Pattern: Standard sections** - ✅ **Confirmed**
- Title with CI badge
- Description: "Installs Pip (Python package manager) on Linux"
- Requirements section (mentions EPEL for RHEL/CentOS)
- Role Variables section with defaults and descriptions
- Dependencies section (None.)
- Example Playbook section
- License and Author Information
- **6/6 roles follow identical README structure**
### Variable Documentation
- **Pattern: Simple variable table** - ✅ **Confirmed**
- pip_package: Default python3-pip, shows alternative for Python 2
- pip_executable: Documents auto-detection, shows override example
- pip_install_packages: Shows list format with dict options
- **All 3 variables documented with defaults and usage context**
- **Pattern: List-of-dicts inline example** - ✅ **Confirmed**
- pip_install_packages shows dict keys: name, version, state, extra_args, virtualenv
- Example shows installing specific version: `docker==7.1.0`
- Shows AWS CLI installation example
- **6/6 roles document list variables with inline examples**
### Requirements Section
- **Pattern: Explicit prerequisites** - ✅ **Confirmed**
- States: "On RedHat/CentOS, you may need to have EPEL installed"
- Recommends geerlingguy.repo-epel role
- **Key insight:** Even simple roles document prerequisites
### Example Playbook
- **Pattern: Single basic example** - ✅ **Confirmed**
- Shows installing 2 packages (docker, awscli)
- Demonstrates vars: section with pip_install_packages
- Clean, minimal example for utility role
- **Validates:** Simple roles don't need complex examples
### Key Validation Findings
**What pip Role Confirms:**
1. ✅ README structure universal even for minimal roles (6/6 roles)
2. ✅ All variables documented even when only 3 total (6/6 roles)
3. ✅ CI badge present even for simple roles (6/6 roles)
4. ✅ Example playbooks scaled appropriately (simple role = simple example)
5. ✅ Prerequisites documented even when minimal
**Pattern Confidence After pip Validation (6/6 roles):**
- **README structure:** UNIVERSAL (6/6 roles identical)
- **Variable documentation:** UNIVERSAL (6/6 document all variables)
- **CI badges:** UNIVERSAL (6/6 roles have them)
- **Example playbooks:** UNIVERSAL (6/6, scaled to complexity)
## Validation: geerlingguy.git
**Analysis Date:** 2025-10-23
**Repository:** <https://github.com/geerlingguy/ansible-role-git>
### README Structure
- **Pattern: Standard sections** - ✅ **Confirmed**
- Title with CI badge
- Description: "Installs Git, a distributed version control system"
- Requirements section (None.)
- Role Variables section with comprehensive variable list
- Dependencies section (None.)
- Example Playbook section
- License and Author Information
- **7/7 roles follow identical README structure**
### Variable Documentation
- **Pattern: Grouped variables** - ✅ **Confirmed**
- git_packages: Package list with platform-specific defaults
- git_install_from_source: Boolean flag with clear purpose
- Source install variables grouped together (workspace, version, path, force_update)
- **Key insight:** Utility roles with options group related variables
- **Pattern: Boolean flags clearly explained** - ✅ **Confirmed**
- git_install_from_source: "`false` by default. If set to `true`, installs from source"
- git_install_force_update: Explains version downgrade protection
- **7/7 roles document boolean flag purpose and default**
### Requirements Section
- **Pattern: Explicit "None"** - ✅ **Confirmed**
- States: "None."
- **7/7 roles include Requirements section even if none needed**
### Example Playbook
- **Pattern: Multiple scenarios** - ✅ **Confirmed**
- Shows package installation example
- Implies source installation available via variables
- **Validates:** Utility roles with multiple modes show key scenarios
### Key Validation Findings
**What git Role Confirms:**
1. ✅ README structure universal across all role types (7/7 roles)
2. ✅ Variable grouping for related options (7/7 roles)
3. ✅ Boolean flags clearly explained (7/7 roles)
4. ✅ CI badge standard even for simple roles (7/7 roles)
5. ✅ Documentation scales with role complexity
**Pattern Confidence After git Validation (7/7 roles):**
- **README structure:** UNIVERSAL (7/7 roles identical)
- **Variable documentation:** UNIVERSAL (7/7 document all variables with context)
- **CI badges:** UNIVERSAL (7/7 roles have them)
- **Example playbooks:** UNIVERSAL (7/7 provide working examples)
- **Explicit "None":** UNIVERSAL (7/7 use for empty sections)
- **Variable grouping:** UNIVERSAL (7/7 group related variables)
- **Boolean flag documentation:** UNIVERSAL (7/7 explain purpose clearly)
## Summary
**Universal Patterns Identified:**
1. Consistent README structure (title → requirements → variables → examples → license)
2. CI badges for test status
3. Comprehensive variable documentation with defaults and context
4. Multiple example playbooks (basic → advanced)
5. Explicit "None" statements for empty sections
6. Inline code formatting for variables, files, commands
7. Bold warnings for critical information
8. Commented examples for list variables
9. Show ALL keys for complex dict structures, even optional ones
**Key Takeaways:**
- Variable documentation should include defaults AND context
- Examples should progress from simple to complex
- Warnings prevent common mistakes
- Consistent formatting improves readability
- Explicit "None" is better than omitting sections
- Troubleshooting saves support time
- Complex variables need inline documentation showing all available keys
**Next Steps:**
Enhance Virgo-Core role READMEs with:
1. More detailed variable context
2. Troubleshooting sections
3. CI badges (after implementing testing)
4. Additional example scenarios
5. For complex variables, show all available keys with inline comments