proxmox/docs/00-meta/CONTRIBUTOR_GUIDELINES.md

Contributor Guidelines

Last Updated: 2026-03-27
Document Version: 1.1
Status: Active Documentation

---

Overview

This document provides guidelines for contributing to the documentation, including style standards, review process, and approval workflow.

---

Style Guide Reference

Primary Reference:

• DOCUMENTATION_STYLE_GUIDE.md ⭐⭐⭐

Key Standards:

• File naming: UPPERCASE_WITH_UNDERSCORES.md
• Headers: Include Last Updated, Document Version, Status
• Cross-references: Use Related Documentation sections
• Code blocks: Include language identifiers and expected output

---

Contribution Process

Step 1: Identify Need

Ways to contribute:

• Fix errors or outdated information
• Add missing documentation
• Improve existing documentation
• Add examples or use cases
• Create diagrams or visualizations

---

Step 2: Follow Standards

Before contributing:

1. Read DOCUMENTATION_STYLE_GUIDE.md
2. Review similar documents for consistency
3. Use templates where available
4. Follow naming conventions

---

Step 3: Create/Update Document

Where to add docs (directory structure):

• 01-getting-started/ – Prerequisites, quick start, first-time setup
• 02-architecture/ – Network, hardware, VMID, orchestration
• 03-deployment/ – Runbooks, deployment guides, status
• 04-configuration/ – MCP, router, Cloudflare, secrets, SSH, templates
• 05-network/ – NGINX, RPC, Cloudflare routing
• 06-besu/ – Besu allowlist, nodes, validator keys
• 07-ccip/ – CCIP deployment spec
• 08-monitoring/ – Monitoring, block production
• 09-troubleshooting/ – FAQ, QBFT, troubleshooting flows
• 10-best-practices/ – Recommendations, checklists
• 11-references/ – API, paths, token list, network master
• 12-quick-reference/ – Quick refs, cards, templates
• 00-meta/ – Style guide, reviews, task list, metrics

Index: Add new docs to MASTER_INDEX.md in the appropriate section and update the directory tree if needed.

For new documents:

• Use appropriate directory structure (above)
• Follow style guide header format
• Include Related Documentation section
• Add to MASTER_INDEX.md

For updates:

• Update Last Updated date
• Increment Document Version if significant changes
• Update change log if document has one
• Verify all links still work

---

Step 4: Review and Test

Self-review checklist:

• Follows style guide
• All links work
• Code examples tested (if applicable)
• No placeholder content
• Proper cross-references
• Added to index files

---

Step 5: Submit for Review

Review process:

1. Create pull request or notify team
2. Include description of changes
3. Reference related issues/tasks
4. Wait for review approval

---

Approval Workflow

Review Levels

Level 1: Self-Review

• Minor corrections
• Formatting fixes
• Link updates

Level 2: Peer Review

• New documents
• Significant updates
• Configuration changes

Level 3: Team Review

• Architecture changes
• Major procedure changes
• Policy updates

---

Examples and Templates

New Document Template

# Document Title

**Navigation:** [Home](../01-getting-started/README.md) > [Category](../01-getting-started/README.md) > Document Title

**Last Updated:** YYYY-MM-DD  
**Document Version:** 1.0  
**Status:** 🟢 Active Documentation

---

## Overview

[Document purpose and scope]

---

[Content sections]

---

## Related Documentation

- **[MASTER_INDEX](../MASTER_INDEX.md)** ⭐⭐⭐ - Documentation index (in docs/)
- **[DOCUMENTATION_STYLE_GUIDE](DOCUMENTATION_STYLE_GUIDE.md)** ⭐⭐ - Style standards

---

**Last Updated:** YYYY-MM-DD  
**Review Cycle:** [Monthly/Quarterly/As Needed]

---

Common Contribution Types

Adding Examples

Guidelines:

• Use real-world scenarios
• Include expected outputs
• Test examples before documenting
• Update if procedures change

---

Fixing Errors

Process:

1. Identify error
2. Verify correct information
3. Update document
4. Update related documents if needed
5. Test fix

---

Adding Diagrams

Guidelines:

• Use Mermaid for new diagrams
• Follow diagram standards
• Reference in text
• Update visual index

---

Git submodules (proxmox parent repo)

This workspace vendors many repositories under git submodule. Guidelines:

1. Detached HEAD after git submodule update is normal when you are not developing inside the submodule.
2. To contribute code in a submodule: cd into it, git checkout main (or the repo’s default branch), branch/commit as usual, push that submodule’s remote, then at the parent root run git add <path> and commit the updated submodule SHA, then push the parent.
3. Never commit secrets in submodule JSON “reference” files under config/; those snapshots are for public addresses only. See SUBMODULE_HYGIENE.md.
4. Verify clean trees before tagging or CI: bash scripts/verify/submodules-clean.sh from the parent root.

---

Related Documentation

• DOCUMENTATION_STYLE_GUIDE.md ⭐⭐⭐ - Style guide
• MASTER_INDEX.md ⭐⭐⭐ - Documentation index
• SUBMODULE_HYGIENE.md — submodule workflow, explorer remotes, JSON config notes
• DOCUMENTATION_CONSOLIDATION_PLAN.md — consolidation scope; DOCUMENTATION_QUALITY_REVIEW.md — quality review

---

Last Updated: 2026-03-27
Review Cycle: Quarterly